Skip to main content
POST
提交一个异步的研究型 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 进入终态:completedfailedcancelled。当为 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

授权

Authorization
string
header
必填

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

请求头

Idempotency-Key
string
必填

使提交具备幂等性的唯一 key(1 到 191 字符)。使用相同 key 和相同请求指纹重复提交会返回原任务。

Maximum string length: 191

请求体

application/json
query
string
必填

自然语言研究查询。

示例:

"Summarize the main changes in RAG evaluation methods over the past year as a bullet list."

outputSchema
object

用于校验结构化输出的 JSON Schema。

input
object

行处理输入:要处理的行以及排除项。

effort
string

该任务的算力/深度层级。

previousRunId
string

从此前已完成的任务继续。

dataSources
any[]

授予该 Agent 访问权限的第三方数据源(Exa Connect)。

响应

研究任务已受理。Location 响应头指向该任务资源;请轮询直到终态。

一个异步集成任务。由提交调用(HTTP 202)以及轮询/详情调用返回。请按 id 轮询该任务,直到 status 进入终态(completed、failed 或 cancelled)。

id
string

唯一的 AIsa 任务标识符。可用它轮询、列出或取消该任务。

示例:

"iaj_01HZY8Q2M4K7N9V3T6W1X0B2C3"

object
string

始终为 "integration_async_job"。

示例:

"integration_async_job"

endpoint
string

该任务所属的提交 endpoint。

示例:

"/apis/v1/exa/agent/runs"

status
enum<string>

面向用户的生命周期状态。queued 和 running 为非终态;completed、failed 和 cancelled 为终态。

可用选项:
queued,
running,
completed,
failed,
cancelled
createdAt
string<date-time>

任务被受理的时间。

completedAt
string<date-time> | null

任务进入终态的时间。任务仍处于排队或运行中时为 null。

pricing
object
output
any | null

任务结果载荷。仅在 status 为 completed 后出现。对 Agent Runs 而言是结构化的研究结果。

outputExpired
boolean

当结果已超过留存窗口、不再可获取时为 true。

error
object | null

当 status 为 failed 时出现,否则为 null。