---
title: Start research
description: Starts a research run on one bucket in a premium deep mode, ultra or recall, and returns it at once with status running.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Start research

`POST /v1/workspaces/{workspaceId}/research`

Starts a research run on one bucket in a premium deep mode, ultra or recall, and returns it at once with status running. It never waits for the answer: follow the run with Research events, and read it with Get research for one hour after it ends. Ask Standard questions with Answer a question. Requires the viewer role. The bucket must have indexing enabled. An image is a premium feature.

## Authentication

Send `Authorization: Bearer <GRAPHON_API_KEY>`. Read the key from the
GRAPHON_API_KEY environment variable. Never print it.

## Path parameters

- `workspaceId` (string) — The workspace id.

## Request body

- `bucketId` (string) — The bucket id. The bucket must be in the workspace and have indexing enabled.
- `query` (string) — The question to answer. It must contain text. At most 32,000 characters.
- `mode` (string (optional)) — Premium. ultra searches, reads, and searches again inside the bucket. recall keeps looking until it finds nothing new, for questions such as "every time checkout timed out". Each runs up to 600 seconds. Defaults to ultra. Ask a Standard question with Answer a question. One of: ultra, recall.
- `stream` (boolean (optional)) — false: 202 with the running research run at once. true: 200 text/event-stream, the events of the run until it ends, as Research events sends them. Either way the Location header names the run. Defaults to false.
- `history` (object[] (optional)) — Earlier turns, oldest first. At most 32. Stored with the research run. Defaults to none.
- `image` (object (optional)) — Premium. A picture to ask about: PNG, JPEG, or WebP, at most 4 MiB. It adds up to 45 seconds. Graphon keeps no copy.

## Example request

```bash
curl \
  --url "https://api.beta.graphon.ai/v1/workspaces/wspq7ws2np5l8z4/research" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"bucketId":"bktA1b2C3d4E5","query":"Why did checkout stall after the 3 October deploy?","mode":"ultra","stream":false,"history":[]}'
```

## Example response

```json
{
  "research": {
    "id": "rscR7tY2kL9mP",
    "workspaceId": "wsp4k9m2x7q1z8r",
    "bucketId": "bktA1b2C3d4E5",
    "status": "succeeded",
    "mode": "ultra",
    "query": "Why did checkout stall after the 3 October deploy?",
    "history": [],
    "answer": "Release 4.18 raised checkout workers from 8 to 24 but left the database pool at 200 [[SRC:0001]].",
    "sources": [
      {
        "ref": "SRC:0001",
        "key": "incidents/2026-10-03-checkout.pdf",
        "versionId": "ver_3f9c2a7d1e4b4c8a9f0d6b2e5a1c7d3f",
        "score": 0.86,
        "cited": true,
        "location": {
          "page": 2,
          "snippet": "Release 4.18 raised CHECKOUT_WORKERS from 8 to 24. DB_POOL_SIZE stayed at 200."
        }
      }
    ],
    "warnings": [],
    "error": null,
    "imageDescription": null,
    "createdBy": {
      "userId": null,
      "apiKeyId": "apkH3sK8pW2xQ"
    },
    "createdAt": "2026-10-12T09:00:00.000Z",
    "completedAt": "2026-10-12T09:03:42.210Z",
    "expiresAt": "2026-10-12T10:03:42.210Z"
  }
}
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.