Research

Get research

GET/namespaces/{namespace}/collections/{collection}/research/{research}

Read a research run: its status, its last stage, and its answer or error.

PermissionThe key that started the run, or a cluster key. Key scopes and actions.

progress is the last stage of the run. When the run succeeds, answer, sources, image_description, and usage are set. When it fails, error is set, with retryable.
Another key gets 404, as for a run that does not exist.

Request

https://engine.example.com/namespaces/acme/collections/incident-logs/research/rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6

GET /namespaces/acme/collections/incident-logs/research/rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6 HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

A run that succeeded, with its answer and its source map.

{
  "id": "rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "namespace": "acme",
  "collection": "incident-logs",
  "status": "succeeded",
  "mode": "ultra",
  "progress": {
    "stage": "synthesizing",
    "label": "Synthesizing answer",
    "step": 3,
    "total_steps": 3
  },
  "answer": "Checkout requests stalled because the database connection pool was exhausted [[SRC:0001]].",
  "sources": {
    "[SRC:0001]": {
      "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
      "path": "/reports/incident.txt",
      "score": 0.81,
      "is_cited": true,
      "evidence": {
        "kind": "text",
        "text": "Checkout requests stalled because the database connection pool was exhausted.",
        "location": {
          "char_start": 0,
          "char_end": 77
        }
      }
    }
  },
  "image_description": null,
  "usage": {
    "credits": 1
  },
  "error": null,
  "created_at": "2026-10-06T10:00:00Z",
  "updated_at": "2026-10-06T10:00:00Z",
  "completed_at": "2026-10-06T10:00:00Z"
}

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

researchstringrequired

Research run ID with the rsr_ prefix, returned by Create research.

Responses

200Success

A run that succeeded, with its answer and its source map.

application/json

Response headers

x-request-idstringrequired

Request correlation ID. Retain it when investigating a failed or unexpected request.

answerstringrequiredaccepts null

Answer text, once the run succeeds. Citation markers use [[SRC:0001]] and match the [SRC:0001] keys in sources. Otherwise null.

collectionstringrequired

Name of the collection that the run answers from.

completed_atstring (date-time)requiredaccepts null

Time the run ended, as an ISO 8601 UTC timestamp. Null while it runs.

created_atstring (date-time)required

Time the resource was created, as an ISO 8601 UTC timestamp.

errorobjectrequiredaccepts null

Why the run failed, with retryable. Null unless the run failed.

idstringrequired

Immutable research run ID with the rsr_ prefix. Use it to read or cancel the run.

image_descriptionstringrequiredaccepts null

How Engine read the query image, once the run succeeds. Null without an image.

modestringrequired

Answer mode of the run.

standard: One retrieve-and-answer pass, with a 120-second limit.
ultra: Deeper work within the collection, with a 600-second limit.
recall: Deeper work that tries to find every match, with a 600-second limit. Needs a cluster key.

namespacestringrequired

Name of the namespace of the collection.

progressobjectrequiredaccepts null

The last stage of the run, or null before the first one.

sourcesmap<string, object>requiredaccepts null

Map from citation markers to supporting sources, once the run succeeds. Keys omit the marker’s outer brackets. Null when return_sources was false.

statusstringrequired

queued, running, succeeded, failed, or canceled. succeeded, failed, and canceled are terminal states.

queued: Accepted and waiting to start.
running: Engine is working on the answer.
succeeded: The answer is ready.
failed: The run ended with an error.
canceled: The run ended after cancellation.

updated_atstring (date-time)required

Time the resource last changed, as an ISO 8601 UTC timestamp.

usageobjectrequiredaccepts null

What the run used, once it succeeds. Otherwise null.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain x-request-id for investigation. Follow retryable before retrying a write.

Was this page helpful?