--- title: Get research description: Read a research run: its status, its last stage, and its answer or error. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Get research `GET /namespaces/{namespace}/collections/{collection}/research/{research}` Read a research run: its status, its last stage, and its answer or error. **Permission:** The key that started the run, or a cluster key. [API key types and authentication](/engine/reference/authentication.md). 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. ## Example request ```http GET /namespaces/acme/collections/incident-logs/research/rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6 HTTP/1.1 Host: engine.example.com Authorization: Bearer ``` ## Path parameters ### `namespace` **string · required** Namespace name or ns_ ID. It must be visible to this key. ### `collection` **string · required** Collection name or col_ ID within the namespace. It must be visible to this key. ### `research` **string · required** Research run ID with the rsr_ prefix, returned by Create research. ## Responses ### 200 · Success A run that succeeded, with its answer and its source map. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ```json { "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" } ``` #### Response fields ##### `answer` **string · required · nullable** Answer text, once the run succeeds. Citation markers use [[SRC:0001]] and match the [SRC:0001] keys in sources. Otherwise null. ##### `collection` **string · required** Name of the collection that the run answers from. ##### `completed_at` **string (date-time) · required · nullable** Time the run ended, as an ISO 8601 UTC timestamp. Null while it runs. ##### `created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `error` **object · required · nullable** Why the run failed, with retryable. Null unless the run failed. ###### `error.code` **string · required** Machine-readable reason for the failure. Use this value for program logic and message for display or diagnostics. ###### `error.message` **string · required** Human-readable explanation of the failure. Do not parse this text to decide how to retry. ###### `error.retryable` **boolean · required** Whether starting the same research again may succeed. ##### `id` **string · required** Immutable research run ID with the rsr_ prefix. Use it to read or cancel the run. ##### `image_description` **string · required · nullable** How Engine read the query image, once the run succeeds. Null without an image. ##### `mode` **string · required** 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. ##### `namespace` **string · required** Name of the namespace of the collection. ##### `progress` **object · required · nullable** The last stage of the run, or null before the first one. ###### `progress.label` **string · required** Readable name of the stage, for display. ###### `progress.stage` **string · required** Machine-readable name of the stage. ###### `progress.step` **integer · required** Number of this stage, from 1. ###### `progress.total_steps` **integer · required** Number of stages that Engine expects for this run. ##### `sources` **map · required · nullable** Map from citation markers to supporting sources, once the run succeeds. Keys omit the marker’s outer brackets. Null when return_sources was false. ###### `sources[key].evidence` **object · required** One source excerpt with its kind and optional position. ###### `sources[key].evidence.kind` **string · required** Form of the extracted evidence, such as text, transcript, OCR, or a page. - `text`: Extracted text. - `transcript`: Transcript from audio or video. - `ocr`: Text recognized from an image or document page. - `json_path`: Evidence at a JSON path. - `page`: Evidence from a document page. - `image_region`: Evidence from a region of an image. ###### `sources[key].evidence.location` **object · optional · nullable** Position of this evidence within the source. The fields depend on its location type. Omitted when no position is available. ###### TimeSpan ###### `sources[key].evidence.location.end_ms` **integer · required** End of the source excerpt, in milliseconds from the beginning of the audio or video. ###### `sources[key].evidence.location.start_ms` **integer · required** Start of the source excerpt, in milliseconds from the beginning of the audio or video. ###### Page ###### `sources[key].evidence.location.bbox` **array · optional · nullable** Optional bounding box coordinates for a region on the referenced page. ###### `sources[key].evidence.location.page` **integer · required** Page number identifying the evidence in the source. ###### JsonPath ###### `sources[key].evidence.location.json_path` **string · required** JSON path locating the evidence within a structured source. ###### CharSpan ###### `sources[key].evidence.location.char_end` **integer · required** End character offset of the evidence within extracted text. ###### `sources[key].evidence.location.char_start` **integer · required** Start character offset of the evidence within extracted text. ###### `sources[key].evidence.text` **string · required** Extracted source text supporting this match or citation. ###### `sources[key].file_id` **string · required** ID of the source file within the queried collection. ###### `sources[key].is_cited` **boolean · required** Whether the answer cites this source marker. ###### `sources[key].path` **string · required** Logical path of the source file within the collection. ###### `sources[key].score` **number · required** Ranking value for this result. It is not a confidence percentage. ##### `status` **string · required** 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_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ##### `usage` **object · required · nullable** What the run used, once it succeeds. Otherwise null. ###### `usage.credits` **integer · required** Credits metered for this query. ## Errors [Error format and retry guidance](/engine/reference/errors.md). ### 400 · `invalid_request` A field, path, parameter, or conditional request rule is invalid. Correct the request. Unknown fields are rejected. ```json { "error": { "code": "invalid_request", "message": "A field, path, parameter, or conditional request rule is invalid.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 401 · `unauthenticated` The API key is missing, invalid, or revoked. Send an active key in Authorization: Bearer or X-API-Key. ```json { "error": { "code": "unauthenticated", "message": "The API key is missing, invalid, or revoked.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 403 · `forbidden` The key can see the resource but lacks permission for this operation. Use a key with the required action or scope kind. ```json { "error": { "code": "forbidden", "message": "The key can see the resource but lacks permission for this operation.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 404 · `not_found` The resource is absent, deleted, or outside this key’s scope. Check the identifier and the key’s namespace and collection scope. ```json { "error": { "code": "not_found", "message": "The resource is absent, deleted, or outside this key’s scope.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 503 · `temporarily_unavailable` A dependency, cluster readiness condition, or capacity limit prevents this operation. Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write. ```json { "error": { "code": "temporarily_unavailable", "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 500 · `internal_error` An unexpected server failure prevented this request from completing. Retain x-request-id for investigation. Follow retryable before retrying a write. ```json { "error": { "code": "internal_error", "message": "An unexpected server failure prevented this request from completing.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ## Other request languages ### cURL ```bash curl -sS "$GRAPHON_ENGINE_URL/namespaces/acme/collections/incident-logs/research/rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections/incident-logs/research/rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6", headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], }, method="GET", ) with urllib.request.urlopen(request) as response: print(response.read().decode()) ``` ### JavaScript ```javascript const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/namespaces/acme/collections/incident-logs/research/rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6", { method: "GET", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, }, }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.