Fetch one query (turn)

One turn, including its steps, citations, and usage. This is what a background run is polled with.

GET /queries/{id}

Fetch one query (turn)

cURL

curl --request GET \
  --url https://{host}/api/queries/{id} \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "<string>",
  "object": "<string>",
  "session_id": "<string>",
  "created": 123,
  "status": "<string>",
  "input": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "output": [
    {
      "role": "<string>",
      "content": [
        {
          "type": "<string>",
          "text": "<string>"
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "<string>",
      "section_paths": [
        [
          "<string>"
        ]
      ],
      "pages": [
        123
      ],
      "score": 123,
      "grounding": "<string>",
      "kind": "<string>",
      "source_path": "<string>",
      "query_id": "<string>",
      "steps": [
        "<string>"
      ],
      "artifact_name": "<string>",
      "sources": [
        "<string>"
      ]
    }
  ],
  "steps": [
    {
      "step_id": "<string>",
      "status": "<string>",
      "commentary": "<string>",
      "fns": [
        "<string>"
      ],
      "strategy": {
        "kind": "<string>",
        "fns": [
          "<string>"
        ],
        "label": "<string>",
        "scope": [
          "<string>"
        ]
      },
      "tool_calls": [
        {
          "fn": "<string>",
          "category": "<string>",
          "args": {},
          "result": "<unknown>",
          "duration_ms": 123,
          "ok": true,
          "score_space": "<string>",
          "error": "<string>"
        }
      ],
      "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
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123
  },
  "runtime_ms": 123,
  "model": "<string>",
  "error": "<string>",
  "previous_query_id": "<string>",
  "comparison": [
    {
      "workflow": "<string>",
      "query_id": "<string>",
      "model": "<string>"
    }
  ],
  "feedback": {
    "rating": "<string>",
    "comment": "<string>"
  },
  "output_json": {},
  "max_steps": 123,
  "thinking_level": "<string>",
  "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>"
}

Authorizations

bearerAuthapiKey

Authorization · string · header · required

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

Headers

X-Pinecone-Api-Version · string · default: 2026-07

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.

Path Parameters

id · string · required

Query turn id.

Response

200

application/json

The query

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

id · string · required

Turn id, qry_<uuid>.

object · string · required

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

session_id · string · required

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

created · integer<int64> · required

Unix seconds

status · string · required

Where the turn is in its lifecycle.

input · object[] · required

The stored message array (plain-text content).

Show child attributes

output · object[] · required

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

Show child attributes

citations · object[] · required

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

Show child attributes

steps · object[] · required

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

Show child attributes

usage · object · required

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

Show child attributes

runtime_ms · integer<int64> · required

Wall time from turn start to terminal state.

model · string | null

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

error · string | null

Failure detail. Set on a failed turn.

previous_query_id · string | null

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

comparison · object[] | null

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

Show child attributes

feedback · object | null

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

Show child attributes

output_json · object | null

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

max_steps · integer<int64> | null

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

thinking_level · string | null

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

rollup · Response turn rollup · object | null

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

Show child attributes

synthesis · Response synthesis · object | null

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

Show child attributes

trace_ref · string | null

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