Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

Fetch the recorded trace for a query turn

The per-turn debug trace (steps, tool calls, strategy, cost, rollup). Trace persistence is unconditional — every turn lands a trace blob — so this is available once the turn is terminal.

GET /queries/{id}/trace

cURL
curl --request GET \
  --url https://{host}/api/queries/{id}/trace \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>'
Python
import requests

url = "https://{host}/api/queries/{id}/trace"

headers = {
    "Authorization": "Bearer <token>",
    "X-Pinecone-Api-Version": "<x-pinecone-api-version>"
}

response = requests.get(url, headers=headers)

print(response.text)
JavaScript
const options = {method: "GET", headers: {"Authorization": "Bearer <token>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>"}};

fetch("https://{host}/api/queries/{id}/trace", 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/queries/{id}/trace",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-Pinecone-Api-Version: <x-pinecone-api-version>"
  ],
]);

$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"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/api/queries/{id}/trace"

	req, _ := http.NewRequest("GET", url, nil)

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

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

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

	fmt.Println(string(body))

}
Java
HttpResponse<String> response = Unirest.get("https://{host}/api/queries/{id}/trace")
  .header("Authorization", "Bearer <token>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .asString();
Ruby
require 'uri'
require 'net/http'

url = URI("https://{host}/api/queries/{id}/trace")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'

response = http.request(request)
puts response.read_body
200
{
  "steps": [
    {
      "step_id": "<string>",
      "commentary": "<string>",
      "code": "<string>",
      "calls": [
        null
      ],
      "strategy": {
        "kind": "<string>",
        "fns": [
          null
        ],
        "label": "<string>",
        "scope": [
          null
        ]
      },
      "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
      }
    }
  ],
  "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
  }
}
Authorizationstringrequired

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

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
idstringrequired

Query turn id.

Typestring

200 — The trace document

A turn's full-fidelity debug trace. Every turn lands one.

steps?object[]

The turn's reasoning steps, in the order they ran.

Typeobject[]
Show child attributes
step_id?string

Identifies the step within the turn.

Typestring
commentary?string

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

Typestring
code?string

The source string alone, as later rows store it.

Typestring
calls?object[]

The tool calls this step made.

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
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[]
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
rollup?object | null

Null on a turn the runtime never closed. The trace's copy omits the type and query_id the event form carries.

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
Suggest an edit

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

Export
Documentation menu