Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

Run one KnowQL query turn

Send ask and, on a new session, a scope of 1–10 contexts; continue an existing one with

session_id or previous_query_id. Scoped search contexts must be curated, and a scope may not mix work and search contexts. Read the answer from output[].content[].text.

stream and background are mutually exclusive. background: true returns 202 with an in_progress query to poll. stream: true emits an SSE stream whose event: names are the event type (see QueryEvent), closed by a final query frame carrying the whole turn:

id: 1
event: response.created
data: {"type":"response.created","query_id":"qry_8b3d5f1a","session_id":"ses_4f9c1e2a"}

id: 2
event: response.output_text.delta
data: {"type":"response.output_text.delta","query_id":"qry_8b3d5f1a","delta":"Revenue grew 12%..."}

id: 3
event: response.completed
data: {"type":"response.completed","query_id":"qry_8b3d5f1a"}

event: query
data: {"id":"qry_8b3d5f1a","object":"query","status":"completed","output":[...]}

POST /query

cURL
curl --request POST \
  --url https://{host}/api/query \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "ask": "<string>",
  "scope": [
    "<string>"
  ],
  "session_id": "<string>",
  "previous_query_id": "<string>",
  "workflow": "<string>",
  "system_prompt": "<string>",
  "guardrails": "<string>",
  "shape": {},
  "model": "<string>",
  "models": [
    "<string>"
  ],
  "tools": [
    "<string>"
  ],
  "stream": true,
  "background": true,
  "timeout_seconds": 123,
  "max_steps": 123,
  "thinking_level": "<string>",
  "compose": true,
  "retrieval_only": true,
  "pointers_only": true,
  "chunks_only": true,
  "artifacts_only": true,
  "max_retrieved": 123,
  "max_retrieved_chars": 123,
  "comparison_group": "<string>"
}'
Python
import requests

url = "https://{host}/api/query"

payload = {
  "ask": "<string>",
  "scope": [
    "<string>"
  ],
  "session_id": "<string>",
  "previous_query_id": "<string>",
  "workflow": "<string>",
  "system_prompt": "<string>",
  "guardrails": "<string>",
  "shape": {},
  "model": "<string>",
  "models": [
    "<string>"
  ],
  "tools": [
    "<string>"
  ],
  "stream": True,
  "background": True,
  "timeout_seconds": 123,
  "max_steps": 123,
  "thinking_level": "<string>",
  "compose": True,
  "retrieval_only": True,
  "pointers_only": True,
  "chunks_only": True,
  "artifacts_only": True,
  "max_retrieved": 123,
  "max_retrieved_chars": 123,
  "comparison_group": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Pinecone-Api-Version": "<x-pinecone-api-version>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
JavaScript
const options = {method: "POST", headers: {"Authorization": "Bearer <token>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>", "Content-Type": "application/json"}, body: JSON.stringify({
  "ask": "<string>",
  "scope": [
    "<string>"
  ],
  "session_id": "<string>",
  "previous_query_id": "<string>",
  "workflow": "<string>",
  "system_prompt": "<string>",
  "guardrails": "<string>",
  "shape": {},
  "model": "<string>",
  "models": [
    "<string>"
  ],
  "tools": [
    "<string>"
  ],
  "stream": true,
  "background": true,
  "timeout_seconds": 123,
  "max_steps": 123,
  "thinking_level": "<string>",
  "compose": true,
  "retrieval_only": true,
  "pointers_only": true,
  "chunks_only": true,
  "artifacts_only": true,
  "max_retrieved": 123,
  "max_retrieved_chars": 123,
  "comparison_group": "<string>"
})};

fetch("https://{host}/api/query", options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/api/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"ask\":\"<string>\",\"scope\":[\"<string>\"],\"session_id\":\"<string>\",\"previous_query_id\":\"<string>\",\"workflow\":\"<string>\",\"system_prompt\":\"<string>\",\"guardrails\":\"<string>\",\"shape\":{},\"model\":\"<string>\",\"models\":[\"<string>\"],\"tools\":[\"<string>\"],\"stream\":true,\"background\":true,\"timeout_seconds\":123,\"max_steps\":123,\"thinking_level\":\"<string>\",\"compose\":true,\"retrieval_only\":true,\"pointers_only\":true,\"chunks_only\":true,\"artifacts_only\":true,\"max_retrieved\":123,\"max_retrieved_chars\":123,\"comparison_group\":\"<string>\"}",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-Pinecone-Api-Version: <x-pinecone-api-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
Go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/query"

	payload := strings.NewReader("{\"ask\":\"<string>\",\"scope\":[\"<string>\"],\"session_id\":\"<string>\",\"previous_query_id\":\"<string>\",\"workflow\":\"<string>\",\"system_prompt\":\"<string>\",\"guardrails\":\"<string>\",\"shape\":{},\"model\":\"<string>\",\"models\":[\"<string>\"],\"tools\":[\"<string>\"],\"stream\":true,\"background\":true,\"timeout_seconds\":123,\"max_steps\":123,\"thinking_level\":\"<string>\",\"compose\":true,\"retrieval_only\":true,\"pointers_only\":true,\"chunks_only\":true,\"artifacts_only\":true,\"max_retrieved\":123,\"max_retrieved_chars\":123,\"comparison_group\":\"<string>\"}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
Java
HttpResponse<String> response = Unirest.post("https://{host}/api/query")
  .header("Authorization", "Bearer <token>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .header("Content-Type", "application/json")
  .body("{\"ask\":\"<string>\",\"scope\":[\"<string>\"],\"session_id\":\"<string>\",\"previous_query_id\":\"<string>\",\"workflow\":\"<string>\",\"system_prompt\":\"<string>\",\"guardrails\":\"<string>\",\"shape\":{},\"model\":\"<string>\",\"models\":[\"<string>\"],\"tools\":[\"<string>\"],\"stream\":true,\"background\":true,\"timeout_seconds\":123,\"max_steps\":123,\"thinking_level\":\"<string>\",\"compose\":true,\"retrieval_only\":true,\"pointers_only\":true,\"chunks_only\":true,\"artifacts_only\":true,\"max_retrieved\":123,\"max_retrieved_chars\":123,\"comparison_group\":\"<string>\"}")
  .asString();
Ruby
require 'uri'
require 'net/http'

url = URI("https://{host}/api/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\"ask\":\"<string>\",\"scope\":[\"<string>\"],\"session_id\":\"<string>\",\"previous_query_id\":\"<string>\",\"workflow\":\"<string>\",\"system_prompt\":\"<string>\",\"guardrails\":\"<string>\",\"shape\":{},\"model\":\"<string>\",\"models\":[\"<string>\"],\"tools\":[\"<string>\"],\"stream\":true,\"background\":true,\"timeout_seconds\":123,\"max_steps\":123,\"thinking_level\":\"<string>\",\"compose\":true,\"retrieval_only\":true,\"pointers_only\":true,\"chunks_only\":true,\"artifacts_only\":true,\"max_retrieved\":123,\"max_retrieved_chars\":123,\"comparison_group\":\"<string>\"}"

response = http.request(request)
puts response.read_body
200
{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "model": "<string>",
  "created": 123,
  "status": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": null,
          "text": null
        }
      ]
    }
  ],
  "output_json": {},
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          null
        ]
      ],
      "pages": [
        123
      ],
      "score": 123,
      "grounding": "<string>",
      "kind": "<string>",
      "source_path": "<string>",
      "query_id": "<string>",
      "steps": [
        "<string>"
      ],
      "artifact_name": "<string>",
      "sources": [
        "<string>"
      ]
    }
  ],
  "max_steps": 123,
  "thinking_level": "<string>",
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "strategy": {
        "kind": "<string>",
        "fns": [
          null
        ],
        "label": "<string>",
        "scope": [
          null
        ]
      },
      "tool_calls": [
        null
      ],
      "code": "<string>",
      "trace_truncated": {
        "truncated": true,
        "dropped_documents": 123,
        "dropped_tool_calls": 123
      },
      "cost": {
        "tokens_in": 123,
        "tokens_out": 123,
        "decide_ms": 123,
        "execute_ms": 123,
        "tokens_in_cached": 123,
        "tokens_in_cache_write": 123,
        "tokens_in_fresh": 123
      },
      "input_tokens": 123,
      "output_tokens": 123,
      "total_tokens": 123,
      "cum_input_tokens": 123,
      "cum_output_tokens": 123
    }
  ],
  "rollup": {
    "type": "<string>",
    "query_id": "<string>",
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123,
    "cache_read_tokens": 123,
    "cache_write_tokens": 123
  },
  "synthesis": {
    "type": "<string>",
    "query_id": "<string>",
    "status": "<string>",
    "tokens_in": 123,
    "tokens_out": 123,
    "ms": 123,
    "answer_preview": "<string>",
    "tokens_in_cached": 123,
    "tokens_in_cache_write": 123,
    "tokens_in_fresh": 123
  },
  "trace_ref": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123
}
202
{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "model": "<string>",
  "created": 123,
  "status": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": null,
          "text": null
        }
      ]
    }
  ],
  "output_json": {},
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          null
        ]
      ],
      "pages": [
        123
      ],
      "score": 123,
      "grounding": "<string>",
      "kind": "<string>",
      "source_path": "<string>",
      "query_id": "<string>",
      "steps": [
        "<string>"
      ],
      "artifact_name": "<string>",
      "sources": [
        "<string>"
      ]
    }
  ],
  "max_steps": 123,
  "thinking_level": "<string>",
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "strategy": {
        "kind": "<string>",
        "fns": [
          null
        ],
        "label": "<string>",
        "scope": [
          null
        ]
      },
      "tool_calls": [
        null
      ],
      "code": "<string>",
      "trace_truncated": {
        "truncated": true,
        "dropped_documents": 123,
        "dropped_tool_calls": 123
      },
      "cost": {
        "tokens_in": 123,
        "tokens_out": 123,
        "decide_ms": 123,
        "execute_ms": 123,
        "tokens_in_cached": 123,
        "tokens_in_cache_write": 123,
        "tokens_in_fresh": 123
      },
      "input_tokens": 123,
      "output_tokens": 123,
      "total_tokens": 123,
      "cum_input_tokens": 123,
      "cum_output_tokens": 123
    }
  ],
  "rollup": {
    "type": "<string>",
    "query_id": "<string>",
    "n_steps": 123,
    "n_tool_calls": 123,
    "by_category": {},
    "total_hits": 123,
    "duration_ms": 123,
    "cache_read_tokens": 123,
    "cache_write_tokens": 123
  },
  "synthesis": {
    "type": "<string>",
    "query_id": "<string>",
    "status": "<string>",
    "tokens_in": 123,
    "tokens_out": 123,
    "ms": 123,
    "answer_preview": "<string>",
    "tokens_in_cached": 123,
    "tokens_in_cache_write": 123,
    "tokens_in_fresh": 123
  },
  "trace_ref": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123
}

Authorizations

Section titled “Authorizations”
Authorizationstringrequired

Session token from POST /auth/login, sent as Authorization: Bearer <token>.

Headers

Section titled “Headers”
X-Pinecone-Api-Version?string

Date-based contract version, echoed back on the same header. Omit for the default (2026-07); send unstable for the in-development surface. An unrecognized value is rejected with 400 unsupported_api_version.

Typestring
Default2026-07

Body

Section titled “Body”
askstringrequired

The natural-language question

Typestring
scope?string[]

Context slugs/UUIDs. New session only; pinned for the session's life. A scope may not mix work and search contexts.

Typestring[]
session_id?string

Continue an existing session

Typestring
previous_query_id?string

Continue the session this query belongs to

Typestring
workflow?string

Search workflow for this turn. Ignored for work contexts, which always run the work runtime.

Typestring
system_prompt?string

Instructions pinned to a new session

Typestring
guardrails?string

Guardrails pinned to a new session

Typestring
shape?object

JSON Schema subset for structured output; result in output_json

Typeobject
model?string

A catalog model id from GET /models, or a tier name (lite, standard, pro) to let the deployment resolve one. New session only; pinned for the session's life.

Typestring
models?string[]

Ordered fallback list, tried in turn. Takes precedence over model.

Typestring[]
tools?string[]

Tool names the turn may call. New session only; pinned for the session's life.

Typestring[]
stream?boolean

SSE streaming. Mutually exclusive with background.

Typeboolean
background?boolean

Fire-and-forget: 202 + in_progress query; poll GET /queries/id. Mutually exclusive with stream.

Typeboolean
timeout_seconds?integer

May only LOWER the 15-minute (900s) cap

Typeinteger
max_steps?integer

Cap the agent's tool-loop steps for this turn

Typeinteger
thinking_level?string

Gemini reasoning depth. Default low. Gemini-backed workflows only; ignored for search_cc.

Typestring
compose?boolean

Set false to skip synthesis, the same as retrieval_only.

Typeboolean
retrieval_only?boolean

Skip synthesis; return retrieved hits in output_json

Typeboolean
pointers_only?boolean

Skip synthesis; return just pointers in output_json

Typeboolean
chunks_only?boolean

Retrieval-only, narrowed to chunks

Typeboolean
artifacts_only?boolean

Retrieval-only, narrowed to artifacts

Typeboolean
max_retrieved?integer

Cap the item count for retrieval-only turns

Typeinteger
max_retrieved_chars?integer

Cap per-item verbatim text length for retrieval-only turns

Typeinteger
comparison_group?string

Client-generated id shared by the turns of one Compare run, so a query cap counts them as one action rather than several. Where the cap applies, a group is limited to 3 turns and a fourth is refused with 409. Omit for a normal query.

Typestring

Response

Section titled “Response”

200 — The completed query turn (synchronous), or the SSE stream when stream=true

One query turn. Read the answer from output[].content[].text.

idstringrequired

Turn id, qry_<uuid>.

objectstringrequired

Always query, so a caller can tell this document apart from a session.

Typestring
session_idstringrequired

The session this turn belongs to. A turn that started a new one names it here.

Typestring
model?string | null

The model that actually answered. Null before the turn resolves one.

Typestring | null
createdintegerrequired

Unix seconds

Typeinteger
statusstringrequired

Where the turn is in its lifecycle.

Typestring
error?string | null

Failure detail. Set on a failed turn.

Typestring | null
previous_query_id?string | null

The turn this one continues. Null on a session's first turn.

Typestring | null
comparison?object[] | null

The sibling turns of the same Compare run. Null on a normal single query.

Typeobject[] | null
Show child attributes
workflow?string

The workflow that turn ran.

Typestring
query_id?string

That turn's id. Fetch it with GET /queries/id.

Typestring
model?string

The model that answered it.

Typestring
feedback?object | null

Thumbs-up/down recorded on this turn. Null until a caller submits some.

Typeobject | null
Show child attributes
rating?string

Thumbs up or down.

Typestring
comment?string | null

Free-text note. Null when none was given.

Typestring | null
inputobject[]required

The stored message array (plain-text content).

Typeobject[]
Show child attributes
rolestringrequired

Who sent the message, e.g. user.

Typestring
contentstringrequired

The message text.

Typestring
outputobject[]required

Output items; assistant text is role, content:[type: output_text, text]

Typeobject[]
Show child attributes
rolestringrequired

Who produced it, e.g. assistant.

Typestring
contentobject[]required

The item's content parts.

Typeobject[]
Show child attributes
typestringrequired

Part kind. output_text carries the answer.

Typestring
textstringrequired

The text of this part.

Typestring
output_json?object | null

Present when a shape was used, or on a retrieval-only turn

Typeobject | null
citationsobject[]required

What the answer was grounded in. Empty on a turn that cited nothing.

Typeobject[]
Show child attributes
source?string

Path of the cited corpus file, relative to the source-tree root.

Typestring
section_paths?string[][]

Heading paths within the source, when known. One inner array per cited section, outermost heading first.

Typestring[][]
pages?integer[]

1-based page numbers, for sources that paginate.

Typeinteger[]
score?number

Retrieval score — how well this source answered the ask. Comparable only within one turn.

Typenumber
grounding?string

The quoted span the answer rests on.

Typestring
kind?string

Which index the citation came out of, e.g. chunk or artifact.

Typestring
source_path?string

Work contexts — path of the artifact the fact was consolidated into.

Typestring
query_id?string

Work contexts — the earlier turn the fact was learned from.

Typestring
steps?string[]

Work contexts — step ids within that earlier turn.

Typestring[]
artifact_name?string

Work contexts — name of the cited artifact.

Typestring
sources?string[]

The documents a cited artifact was derived from.

Typestring[]
max_steps?integer | null

The agentic tool-loop step cap this turn actually ran with, whether the request set it or the deployment default supplied it.

Typeinteger | null
thinking_level?string | null

The thinking level this turn actually ran at. Null on the Claude-backed search_cc, which has no equivalent knob.

Typestring | null
stepsobject[]required

The turn's reasoning steps, reduced from its response.step events.

Typeobject[]
Show child attributes
step_idstringrequired

Identifies the step within the turn. Clients merge repeated events by it.

Typestring
statusstringrequired

How far the step has got.

Typestring
commentarystringrequired

The model's own one-line account of what this step is doing.

Typestring
fns?string[]

Tool functions this step called.

Typestring[]
strategy?object

The retrieval approach the step picked.

Typeobject
Show child attributes
kind?string

Strategy family, e.g. artifacts_first.

Typestring
fns?string[]

Tool functions the strategy calls.

Typestring[]
label?string

Display label for the strategy.

Typestring
scope?string[]

Context ids the strategy searched.

Typestring[]
tool_calls?object[]

Per-call detail for the step's tool calls.

Typeobject[]
Show child attributes
fn?string

Name of the function this call invoked.

Typestring
category?string

Which family the tool belongs to, as tallied in the rollup's by_category.

Typestring
args?object

Compact, redacted summary of the call's arguments. The key set is tool-specific and deliberately open.

Typeobject
result?any

Compact summary of the call's result (never the payload). The shape varies by category and is runtime-extensible.

Typeany
duration_ms?integer

Wall time for this one call.

Typeinteger
ok?boolean

Whether the call succeeded.

Typeboolean
score_space?string

Which scoring space the returned scores live in, for calls that retrieve.

Typestring
error?string

Failure detail. Set when ok is false.

Typestring
code?string

The source string alone, as later rows store it.

Typestring
trace_truncated?object

What a clamp shed from an oversized step event.

Typeobject
Show child attributes
truncated?boolean

Whether the clamp fired at all.

Typeboolean
dropped_documents?integer

Retrieved documents shed from the event.

Typeinteger
dropped_tool_calls?integer

How many calls the clamp discarded.

Typeinteger
cost?object

The step's incremental token and latency cost — deltas against the running turn cursor, not totals. The cache fields are tracked only on the search-as-code path.

Typeobject
Show child attributes
tokens_in?integer

The step's input tokens.

Typeinteger
tokens_out?integer

The step's output tokens.

Typeinteger
decide_ms?integer

Time spent choosing what to do.

Typeinteger
execute_ms?integer

Time spent running the tool calls it chose.

Typeinteger
tokens_in_cached?integer

Input tokens served from the prompt cache.

Typeinteger
tokens_in_cache_write?integer

Input tokens written into the prompt cache.

Typeinteger
tokens_in_fresh?integer

Input tokens neither cached nor cache-written.

Typeinteger
input_tokens?integer

Prompt tokens billed by this one step.

Typeinteger
output_tokens?integer

Completion tokens billed by this one step.

Typeinteger
total_tokens?integer

Prompt plus completion for this one step.

Typeinteger
cum_input_tokens?integer

Turn-to-date input tokens, including this step.

Typeinteger
cum_output_tokens?integer

Turn-to-date output tokens, including this step.

Typeinteger
rollup?object | null

End-of-turn counters. Null on a turn the runtime never closed.

Typeobject | null
Show child attributes
type?string

Event form only.

Typestring
query_id?string

Event form only.

Typestring
n_steps?integer

Reasoning steps the turn ran.

Typeinteger
n_tool_calls?integer

How many calls the whole turn made.

Typeinteger
by_category?object

Tool calls tallied by category.

Typeobject
total_hits?integer

Retrieved items across all calls, before dedup.

Typeinteger
duration_ms?integer

Wall time for the whole turn.

Typeinteger
cache_read_tokens?integer

Input tokens served from the prompt cache.

Typeinteger
cache_write_tokens?integer

Input tokens written into the prompt cache.

Typeinteger
synthesis?object | null

The answer completion's cost. Null on a turn that skipped synthesis, as retrieval-only turns do.

Typeobject | null
Show child attributes
type?string

Event form only.

Typestring
query_id?string

Event form only.

Typestring
status?string

How synthesis ended, e.g. completed.

Typestring
tokens_in?integer

The completion's input tokens.

Typeinteger
tokens_out?integer

The completion's output tokens.

Typeinteger
ms?integer

Wall time of the completion.

Typeinteger
answer_preview?string

Leading characters of the answer, for a progress display that has no full text yet.

Typestring
tokens_in_cached?integer

Input tokens served from the prompt cache.

Typeinteger
tokens_in_cache_write?integer

Input tokens written into the prompt cache.

Typeinteger
tokens_in_fresh?integer

Input tokens neither cached nor cache-written.

Typeinteger
trace_ref?string | null

Blob key of the persisted trace. Fetch the trace itself from GET /queries/id/trace.

Typestring | null
usageobjectrequired

The turn's token totals. Embed and rerank bill on their own seam and are not counted here.

Typeobject
Show child attributes
input_tokensintegerrequired

Input tokens the turn billed.

Typeinteger
output_tokensintegerrequired

Output tokens the turn billed.

Typeinteger
total_tokensintegerrequired

Input plus output tokens.

Typeinteger
runtime_msintegerrequired

Wall time from turn start to terminal state.

Typeinteger
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu