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.

View as Markdown

Authentication

Send your Graphon API key with every request. The value is the whole API key that Graphon showed when you created it. See Authentication.

Authorization: Bearer <GRAPHON_API_KEY>

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":[]}'

Request

Loading your session…

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

Path parameters

workspaceIdstring

The workspace id.

Request body

bucketIdstring

The bucket id. The bucket must be in the workspace and have indexing enabled.

querystring

The question to answer. It must contain text. At most 32,000 characters.

modestring (optional)Premium: ultra, recall

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.

streamboolean (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.

historyobject[] (optional)

Earlier turns, oldest first. At most 32. Stored with the research run. Defaults to none.

imageobject (optional)Premium

Premium. A picture to ask about: PNG, JPEG, or WebP, at most 4 MiB. It adds up to 45 seconds. Graphon keeps no copy.

Was this page helpful?