> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Exa Agent Runs

> 以异步任务方式向 Exa Agent 提交研究任务——先提交，然后轮询该任务的状态和结果。

提交一个自然语言研究 `query`，Exa Agent 会在后台执行并返回结构化结果。由于深度研究耗时较长，Agent Runs 是一个**异步任务**：先提交任务，然后轮询获取状态和结果。

**生命周期**

1. **提交** —— `POST /apis/v1/exa/agent/runs`，带上研究请求体和必填的 `Idempotency-Key` 请求头。成功后返回 `202 Accepted`、指向任务资源的 `Location` 响应头（`/apis/v1/exa/agent/runs/{jobId}`），以及一个 `status` 初始为 `queued` 的任务对象。使用相同的 key 和相同的请求体重复提交会返回原任务；相同 key 但请求体不同则返回 `409 idempotency_conflict`。
2. **轮询** —— `GET /apis/v1/exa/agent/runs/{jobId}`，重复直到 `status` 进入终态：`completed`、`failed` 或 `cancelled`。当为 `completed` 时，研究结果位于 `output` 中。该提供商仅支持轮询——没有 webhook 或 SSE 回调。
3. **列表** —— `GET /apis/v1/exa/agent/runs`（可选 `status` 过滤，支持分页）用于翻阅你的任务。
4. **取消** —— `POST /apis/v1/exa/agent/runs/{jobId}/cancel` 请求取消；已取消的任务不计费。

可以提供 `outputSchema` 校验结构化输出，用 `effort` 在深度和延迟之间权衡，用 `previousRunId` 继续之前的任务，并用 `input`/`dataSources` 处理行数据和 Exa Connect 来源。按每次任务固定 **\$0.10** 计费。如果只需要一次性的带引用答案，而不是多步任务，请使用 [`post_exa-answer`](/docs/zh/api-reference/search/post_exa-answer)。


## OpenAPI

````yaml openapi/zh/exa.json POST /exa/agent/runs
openapi: 3.0.0
info:
  title: Exa API
  version: 1.0.0
  description: >-
    通过 AIsa 网关开放的 Exa 神经语义搜索 endpoint 的统一 API 文档：Search、Contents、Answer，以及异步的研究型
    Agent Runs。


    Search、Contents 和 Answer 为同步接口，每次成功请求固定计费 $0.08。Agent Runs
    为异步接口：调用方提交任务，然后轮询返回的任务资源以获取状态和结果，每次任务固定计费 $0.10。上游 4xx 响应（例如
    401/403/404）不计费。Exa 返回的 `costDollars` 字段是上游成本明细，仅供参考——客户计费以上述 AIsa 固定价格为准。
servers:
  - url: https://api.aisa.one/apis/v1
security:
  - bearerAuth: []
paths:
  /exa/agent/runs:
    post:
      tags:
        - https://docs.exa.ai/reference/create-a-research-task
      summary: 提交一个异步的研究型 Agent 任务。
      description: >-
        异步接口。提交一个自然语言研究任务；Agent 在后台执行并返回结构化结果。按每次任务固定 $0.10 计费。


        生命周期：

        1. 提交 —— POST /exa/agent/runs，带上研究请求体和必填的 `Idempotency-Key` 请求头。成功时 API
        返回 HTTP 202 Accepted、指向任务资源的 `Location`
        响应头（`/apis/v1/exa/agent/runs/{jobId}`），以及 `status` = queued 的
        integration_async_job 响应体。使用相同 key 和相同请求指纹重复提交会返回原任务；相同 key 但指纹不同则返回 409
        idempotency_conflict。

        2. 轮询 —— GET /apis/v1/exa/agent/runs/{jobId} 获取任务。重复直到 `status`
        进入终态（completed、failed 或 cancelled）。完成时，研究结果位于 `output` 中。该提供商仅支持轮询（没有
        webhook 或 SSE 回调）。

        3. 列表 —— GET /apis/v1/exa/agent/runs（可选 status 过滤，支持分页）用于翻阅该 endpoint
        下的任务。

        4. 取消 —— POST /apis/v1/exa/agent/runs/{jobId}/cancel 请求取消。已取消的任务不计费。
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
            maxLength: 191
          description: 使提交具备幂等性的唯一 key（1 到 191 字符）。使用相同 key 和相同请求指纹重复提交会返回原任务。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: 自然语言研究查询。
                  example: >-
                    Summarize the main changes in RAG evaluation methods over
                    the past year as a bullet list.
                outputSchema:
                  type: object
                  description: 用于校验结构化输出的 JSON Schema。
                input:
                  type: object
                  description: 行处理输入：要处理的行以及排除项。
                  properties:
                    data:
                      type: array
                      items: {}
                      description: 该任务的输入行。
                    exclusion:
                      description: 要排除在处理之外的条目。
                effort:
                  type: string
                  description: 该任务的算力/深度层级。
                previousRunId:
                  type: string
                  description: 从此前已完成的任务继续。
                dataSources:
                  type: array
                  items: {}
                  description: 授予该 Agent 访问权限的第三方数据源（Exa Connect）。
              required:
                - query
      responses:
        '202':
          description: 研究任务已受理。Location 响应头指向该任务资源；请轮询直到终态。
          headers:
            Location:
              schema:
                type: string
              description: 所创建任务资源的路径，例如 /apis/v1/exa/agent/runs/{jobId}。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJob'
        '409':
          description: idempotency_conflict——同一个 Idempotency-Key 被用于了不同的请求体。
components:
  schemas:
    AsyncJob:
      type: object
      description: >-
        一个异步集成任务。由提交调用（HTTP 202）以及轮询/详情调用返回。请按 id 轮询该任务，直到 status
        进入终态（completed、failed 或 cancelled）。
      properties:
        id:
          type: string
          description: 唯一的 AIsa 任务标识符。可用它轮询、列出或取消该任务。
          example: iaj_01HZY8Q2M4K7N9V3T6W1X0B2C3
        object:
          type: string
          description: 始终为 "integration_async_job"。
          example: integration_async_job
        endpoint:
          type: string
          description: 该任务所属的提交 endpoint。
          example: /apis/v1/exa/agent/runs
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
          description: 面向用户的生命周期状态。queued 和 running 为非终态；completed、failed 和 cancelled 为终态。
        createdAt:
          type: string
          format: date-time
          description: 任务被受理的时间。
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: 任务进入终态的时间。任务仍处于排队或运行中时为 null。
        pricing:
          type: object
          properties:
            currency:
              type: string
              example: USD
            authorizedMicrosUSD:
              type: integer
              description: 任务被受理时授权（冻结）的金额，单位为微美元。Agent Runs 按每次任务固定 $0.10 结算。
            finalMicrosUSD:
              type: integer
              nullable: true
              description: 任务进入终态后的最终结算金额，单位为微美元。结算前为 null。
            billingMode:
              type: string
              description: 该任务的计费模式。
              example: flat_per_call
        output:
          description: 任务结果载荷。仅在 status 为 completed 后出现。对 Agent Runs 而言是结构化的研究结果。
          nullable: true
        outputExpired:
          type: boolean
          description: 当结果已超过留存窗口、不再可获取时为 true。
        error:
          type: object
          nullable: true
          description: 当 status 为 failed 时出现，否则为 null。
          properties:
            code:
              type: string
              description: 机器可读的错误码。
            message:
              type: string
              description: 人类可读的错误信息。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````