# Research

`POST /v1/research`

Searches, reads and answers with cited sources. fast answers within the request, deep runs in the background, and auto chooses for you.

## Request body

- `query` (string): Required. What to search for or research. Non-empty, up to 2,000 characters.

- `mode` (string): fast for a quick answer, deep for in-depth research, auto to choose by query. Default: auto

## Response

- `id` (string): Run id, for getting, cancelling or deleting the Run.

- `status` (string): queued, running, completed, failed or cancelled.

- `created_at` (string): When the Run was created.

- `started_at` (string | null): When the Run started; null before then.

- `completed_at` (string | null): When the Run ended; null until then.

- `mode` (string): The mode the Run used: fast or deep.

- `message` (string): A polling hint while the Run is in progress.

- `requested_mode` (string): The mode you requested.

- `error.code` (string): Why the Run failed. Present only when status is failed.

- `error.retryable` (boolean): Whether running the same query again may succeed.

- `result.answer` (string): The answer, once the Run is completed.

- `result.sources` (object[]): Cited sources, each with title and url.

## Runs

A fast request waits up to 20 seconds and returns 200 with the finished Run. deep, or a Run still going when the wait ends, returns 202 with its id: get it until status is completed, failed or cancelled. Send Prefer: respond-async to return at once, or Prefer: wait=N to wait at most N seconds.

| Operation | Request | Result |
| --- | --- | --- |
| Get | `GET /v1/research/{id}` | The Run as it is now. While it is queued or running, get it again after Retry-After. |
| Cancel | `POST /v1/research/{id}/cancel` | 200 once cancelled, 202 while cancellation finishes. A Run that has already ended returns 409 run_not_cancellable. |
| Delete | `DELETE /v1/research/{id}` | 204 once deleted. 202 while a running Run is stopped and deleted; it then returns 404. |

Use the API key that created a Run for every operation on it.

## Request

```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"}'
```

## Response 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"
      }
    ]
  }
}
```

## Response 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."
}
```

See also: [Authentication](/platform/docs/concepts/authentication.md?locale=en) · [Errors](/platform/docs/concepts/errors.md?locale=en) · [Rate limits](/platform/docs/concepts/rate-limits.md?locale=en)