Research a bucket

Overview

Research answers one hard question about one bucket. It works on its own for minutes: it searches, reads what it found, and searches again with what it learned. The answer carries the same citation markers as Answer.

Reach for it when a single pass is not enough: a question that needs many reads, or a complete list where a missed match is the failure. For an ordinary question, Answer returns in seconds and costs less.

target names what to research: a bucket id (bkt…) or a dataset id (dst…). The run belongs to your workspace in both cases. To research a dataset that Graphon curates, read Query a dataset.

Cost and limits

Research is premium, and each run takes at most 600 seconds. The request takes no mode, and a request that sends one returns 400 invalid_request. Ask ordinary questions with Answer a question.

Start a run

The call never waits for the answer. It returns at once with a running run, and the Location header names it.

graphon research start support-tickets \
  "Every incident where checkout ran out of database connections" --watch
graphon research get rscR7tY2kL9mP

curl --request POST \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/research" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "target": "'"$GRAPHON_BUCKET_ID"'",
    "query": "Every incident where checkout ran out of database connections"
  }'

HTTP/1.1 202 Accepted
Location: /v1/workspaces/wsp4k9m2x7q1z8r/research/rscR7tY2kL9mP

{
  "research": {
    "id": "rscR7tY2kL9mP",
    "status": "running",
    "query": "Every incident where checkout ran out of database connections",
    "answer": null,
    "sources": [],
    "createdAt": "2026-10-12T09:00:00.000Z",
    "completedAt": null,
    "expiresAt": null
  }
}

Keep the id. It is the only way back to the run.

Follow the run

Read the run's events as a server-sent event stream. Each run.progress event names the step and how many there are, so you can show the reader that work is happening.

curl --no-buffer \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/research/$RESEARCH_ID/events" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Accept: text/event-stream" \
  --header "Last-Event-ID: 1"

event: run.progress
id: 4
data: {"label":"Reading the October incident reports","step":2,"totalSteps":7}

event: run.succeeded
id: 9
data: {"run":{"id":"rscR7tY2kL9mP","status":"succeeded","answer":"Three incidents...","sources":[...]}}

The stream sends a comment every 15 seconds, so an idle connection stays open. It closes after the run's last event, or after 55 minutes. Send the last id you saw in Last-Event-ID to rejoin, and no event is missed. A run that has already ended sends its events at once and closes.

To start a run and read the same stream on one call, send "stream": true. The response is then 200 text/event-stream instead of 202.

Read the answer

GET /research/{researchId} returns the run as it stands and never waits. Its status is running, then succeeded or failed, and it never goes back.

A failed run carries error with a code and retryable. When retryable is true, starting the same research again can succeed.

Next

1. Ask a faster question in Answer a question.
2. Read every field in the Start research reference.