Skip to main content
POST

Authorizations

​
Authorization
string
header
required

The query token returned by Create Query Token, sent as Authorization: Bearer {token}. Use it before the returned expires_at time, at most 60 seconds after issue. It authorizes only Run Query on that knowledge base.

Send X-Trace-ID on the same request, with the trace_id that Create Query Token returned.

Headers

​
X-Trace-ID
string
required

The trace_id from the Create Query Token response, the same value as the token's trace_id claim. A value that does not match the token is rejected with 403. See Query the Knowledge Base.

Body

application/json

Send the request object from Create Query Token unchanged. Unknown fields answer 400.

Optional fields marked nullable treat null as omitted.

The normalized request must fit within 65,536 UTF-8 bytes. Exceeding this budget answers 413. See Request Size Limits.

Provide a nonblank query.

​
knowledgeSpaceId
string<uuid>
required

Internal ID of the knowledge base, copied from the request object of Create Query Token. Must match the token. A mismatch is rejected with 403.

Minimum string length: 1
​
query
string
required

The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes.

Maximum string length: 16000
Pattern: \S
​
activeDocumentIds
string<uuid>[]

Copied from the returned request object. These IDs do not filter or rank retrieved content.

Maximum array length: 100
​
activeEntityIds
string[]

Copied from the returned request object. These IDs do not filter or rank retrieved content.

Maximum array length: 100
Required string length: 1 - 200
​
mode
enum<string> | null

Retrieval depth, copied from the request object of Create Query Token. null is accepted and means the knowledge base's default depth.

Available options:
fast,
deep,
research,
null
​
sessionId
string<uuid> | null

Session ID, copied from the request object of Create Query Token.

Response

The stream opened. Events follow as text/event-stream, whatever Accept the request sends. Before the stream opens, handle failures as HTTP errors. After it opens, handle an answer.error event as failure even though the HTTP status is 200.

Each frame has an event: line naming the event and a data: line holding one JSON object. Dispatch on the event: line; the JSON carries no event field.

Set your client's read timeout to allow for your slowest retrieval mode. The API has no read timeout of its own and sends no keep-alive events. For work that must survive a client timeout, use Create Research Task.

See Query the Knowledge Base for the streaming flow.

Events

  • answer.delta: one piece of the answer.
    • delta: the text to append.
    • traceId: the query record ID.
  • answer.done: the answer is complete and its query record is saved.

    • finishReason: retrieval-evidence when chunks were found, no-retrieval-evidence when nothing matched.

    • metadata: an open map. It carries mode and evidenceBundle at fast, deep, and research depth, citations with retrieval-evidence, and other keys the run produced. evidenceBundle.items holds the retrieved chunks with their text and scores.

      To inspect them later, call List Query Chunks. It returns them page by page and marks chunks whose document has since been deleted.

    • traceId: the query record ID.

  • answer.error: the query failed after the stream opened.
    • code: the failure, one of:
      • RETRIEVAL_EXECUTION_LEASE_LOST: the knowledge base entered deletion, or the run expired. Run the query again.
      • KNOWLEDGE_FS_UNAVAILABLE: any other failure while generating the answer or saving the query record.
    • error: the message.
    • failure: error details: category, code, message, retryPolicy, stage, traceId, and optionally action.
      • stage: always query_generation.
    • traceId: the query record ID.

citations

One entry per retrieved chunk that supports the answer:

  • nodeId: the chunk ID.
  • label: node:<nodeId>.
  • documentAssetId: the document file the chunk came from.
  • sectionPath: the outline path.
  • pageNumber: page number, starting at 1, when the source provides page information. Omitted otherwise.
  • projectionIds: IDs of the search indexes that contributed to this match. Use documentAssetId to identify the source file.
  • sources: which searches found the chunk: dense, fts, pageindex, or visual.

An image citation can include multimodalCandidate.assetRef.analysisUnavailable.reason. When present, image analysis was skipped because of a resource limit or an image-processing failure. Related text can still contribute to the result.

evidenceBundle.items[].citations[] may also carry startOffset and endOffset. These are zero-based UTF-8 byte offsets into the parsed document text, with an inclusive start and exclusive end. Use the returned chunk text to display a citation; do not slice the original file at these offsets.

Closing sequence by outcome

  • Success: zero or more answer.delta, then one answer.done, then the stream closes.
  • Failure: answer.error in place of answer.done, then the stream closes. Pieces already delivered may precede it, and the HTTP status stays 200. Treat it as final and start a new query to try again.
  • Client disconnect. The run is canceled and the stream ends.

Answer content: at fast and deep, one answer.delta carries a digest of the retrieved chunks (Retrieval evidence answer: followed by numbered section paths and their text). At research, the synthesized answer streams as one or more pieces. When nothing matched, the single piece is I could not find evidence for that query in the indexed retrieval projections. and finishReason is no-retrieval-evidence.

Answers are capped at 2,000 characters at every depth. Reaching that length does not tell you whether the answer was truncated.

A successful run:

Failure after the stream opened: