Research

Create research

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

Start an answer that runs on its own, and read it later.

PermissionCluster key, or a scoped key with query on this collection. Key scopes and actions.

Send Idempotency-Key. Retry the same logical request with the same key and body. Idempotency records remain available for replay for 24 hours.
The body and its checks are those of Answer, in any mode. recall, web_search use_if_needed, and query_image need a cluster key.
The run starts queued. It moves to running, then ends succeeded, failed, or canceled. The limits of Answer hold: 120 seconds for standard, 600 for ultra and recall, and 45 more with an image.
research.updated reports each status change, and research.progress reports each new stage. Each webhook POST holds a batch of events.
Only this key, or a cluster key, can read or cancel the run.

Request

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

POST /namespaces/acme/collections/incident-logs/research HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json
Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7

{
  "query": "Find every incident in which checkout ran out of database connections.",
  "mode": "ultra",
  "return_sources": true
}

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

Response

202

The run is queued. Read it with Get research, or wait for research.updated.

{
  "id": "rsr_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "namespace": "acme",
  "collection": "incident-logs",
  "status": "queued",
  "mode": "ultra",
  "progress": null,
  "answer": null,
  "sources": null,
  "image_description": null,
  "usage": null,
  "error": null,
  "created_at": "2026-10-06T10:00:00Z",
  "updated_at": "2026-10-06T10:00:00Z",
  "completed_at": null
}

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.

Headers

Idempotency-Keystringrequired

Unique key for this logical operation. Reuse it only with the same request for retries. Retained for 86,400 seconds. A changed body returns idempotency_conflict.

Request body

filterFilterClauseoptionalaccepts null

Structured selection of files to use for the answer. Uses the same grammar as Search. Filters do not replace access rules.

Maximum depth: 8
Maximum clauses: 100
An in list holds 1–100 values.

historyarray<object>optional

Prior conversation turns, oldest first. Maximum 32 messages. Your application stores and resends this history.

Maximum items: 32

modestringoptional

Answer mode. standard performs one retrieve-and-answer pass. ultra performs deeper work within the collection. Check GET /info for supported modes.

Default: "standard"

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.

principalsarray<string>optionalaccepts null

End-user and group identifiers supplied by your server. Required on enforced collections and invalid when access control is off. An empty list gives no results. Maximum 4,096 entries, each at most 256 UTF-8 bytes.

querystringrequired

Question to answer from this collection. Must contain non-space text and be at most 32,000 characters.

Minimum characters: 1
Maximum characters: 32000

query_imageobjectoptionalaccepts null

An image to ask about, read for this query only. Engine does not store or index it. Needs a cluster key, and adds 45 seconds to the time limit.

return_sourcesbooleanoptional

Include the source map for citations. When false, the response omits sources.

Default: true

web_searchstringoptional

Whether the answer may use web search: never (default) or use_if_needed. use_if_needed needs a cluster key, and web search runs only in ultra when the deployment enables it.

Default: "never"

never: Do not use web search.
use_if_needed: Use web search when the collection cannot answer. Needs a cluster key, and runs only in ultra.

Responses

202Accepted

The run is queued. Read it with Get research, or wait for research.updated.

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.

400invalid_filter

A filter uses an unsupported field, operator, value, or nesting structure.

What to do: Use the documented filter grammar and field-specific value types.

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.

409idempotency_conflict

This idempotency key was already used with a different request body.

What to do: Reuse the original body for a retry, or choose a new key for a new operation.

409collection_empty

The collection contains no living files to answer from.

What to do: Add a file and wait for a ready event before querying.

409collection_not_ready

The collection cannot serve this retrieval request yet.

What to do: Read retryable and details.retry_after_seconds. If processing failed, inspect file errors and correct the source.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

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?