# 研究

`POST /v1/research`

检索、阅读并给出带来源引用的答案。fast 在请求内返回答案，deep 在后台运行，auto 自动选择。

## 请求体

- `query` (string): 必填。 要搜索或研究的内容。不能为空，最多 2,000 个字符。

- `mode` (string): fast 快速作答，deep 深入研究，auto 根据问题自动选择。 默认值：auto

## 响应

- `id` (string): Run id，用于查询、取消或删除该 Run。

- `status` (string): queued、running、completed、failed 或 cancelled。

- `created_at` (string): Run 的创建时间。

- `started_at` (string | null): Run 的开始时间；开始前为 null。

- `completed_at` (string | null): Run 的结束时间；结束前为 null。

- `mode` (string): Run 实际使用的模式：fast 或 deep。

- `message` (string): Run 进行中时附带的轮询提示。

- `requested_mode` (string): 请求时指定的模式。

- `error.code` (string): 失败原因，仅在 status 为 failed 时返回。

- `error.retryable` (boolean): 用相同问题重试是否可能成功。

- `result.answer` (string): 答案，Run 完成后返回。

- `result.sources` (object[]): 引用的来源，每项包含 title 和 url。

## Run

fast 请求最多等待 20 秒，返回 200 和已结束的 Run。deep，或等待结束时仍在进行的 Run，返回 202 和 Run id：查询它，直到 status 为 completed、failed 或 cancelled。请求头 Prefer: respond-async 立即返回，Prefer: wait=N 最多等待 N 秒。

| 操作 | 请求 | 结果 |
| --- | --- | --- |
| 查询 | `GET /v1/research/{id}` | 返回 Run 的当前状态。queued 或 running 时，等待 Retry-After 后再查询。 |
| 取消 | `POST /v1/research/{id}/cancel` | 已取消返回 200，取消进行中返回 202。已结束的 Run 返回 409 run_not_cancellable。 |
| 删除 | `DELETE /v1/research/{id}` | 已删除返回 204。运行中的 Run 返回 202，停止并删除后查询会返回 404。 |

对 Run 的所有操作都要使用创建它的 API 密钥。

## 请求示例

```bash
curl "https://api.arex-research.com/v1/research" \
  -H "Authorization: Bearer $AREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Compare current approaches to AI agent evaluation","mode":"auto"}'
```

## 响应 200

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "completed",
  "mode": "fast",
  "requested_mode": "auto",
  "created_at": "2026-09-03T08:00:00Z",
  "started_at": "2026-09-03T08:00:01Z",
  "completed_at": "2026-09-03T08:00:12Z",
  "result": {
    "answer": "AI agent evaluation combines task-success benchmarks with checks of tool use, reliability, and safety.",
    "sources": [
      {
        "title": "AgentBench: Evaluating LLMs as Agents",
        "url": "https://arxiv.org/abs/2308.03688"
      }
    ]
  }
}
```

## 响应 202

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "mode": "deep",
  "requested_mode": "auto",
  "created_at": "2026-09-03T08:00:00Z",
  "message": "Running research (id: 11111111-1111-4111-8111-111111111111). Poll GET /v1/research/11111111-1111-4111-8111-111111111111 until status is completed, failed, or cancelled."
}
```

另请参阅: [身份验证](/platform/docs/concepts/authentication.md?locale=zh) · [错误处理](/platform/docs/concepts/errors.md?locale=zh) · [限流](/platform/docs/concepts/rate-limits.md?locale=zh)