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 --request GET \
--url https://{host}/api/queries/{id}/trace \
--header 'Authorization: Bearer <token>' \
--header 'X-Pinecone-Api-Version: <x-pinecone-api-version>'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)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
$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;
}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))
}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();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{
"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
}
}Authorizations
Section titled “Authorizations”AuthorizationstringrequiredSession token from POST /auth/login, sent as Authorization: Bearer <token>.
Headers
Section titled “Headers”X-Pinecone-Api-Version?stringDate-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
Section titled “Path Parameters”idstringrequiredQuery turn id.
Response
Section titled “Response”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.
Show child attributes
step_id?stringIdentifies the step within the turn.
commentary?stringThe model's own one-line account of what this step is doing.
code?stringThe source string alone, as later rows store it.
calls?object[]The tool calls this step made.
Show child attributes
fn?stringName of the function this call invoked.
category?stringWhich family the tool belongs to, as tallied in the rollup's by_category.
args?objectCompact, redacted summary of the call's arguments. The key set is tool-specific and deliberately open.
result?anyCompact summary of the call's result (never the payload). The shape varies by category and is runtime-extensible.
duration_ms?integerWall time for this one call.
ok?booleanWhether the call succeeded.
score_space?stringWhich scoring space the returned scores live in, for calls that retrieve.
error?stringFailure detail. Set when ok is false.
strategy?objectThe retrieval approach the step picked.
Show child attributes
kind?stringStrategy family, e.g. artifacts_first.
fns?string[]Tool functions the strategy calls.
label?stringDisplay label for the strategy.
scope?string[]Context ids the strategy searched.
cost?objectThe 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.
Show child attributes
tokens_in?integerThe step's input tokens.
tokens_out?integerThe step's output tokens.
decide_ms?integerTime spent choosing what to do.
execute_ms?integerTime spent running the tool calls it chose.
tokens_in_cached?integerInput tokens served from the prompt cache.
tokens_in_cache_write?integerInput tokens written into the prompt cache.
tokens_in_fresh?integerInput tokens neither cached nor cache-written.
rollup?object | nullNull on a turn the runtime never closed. The trace's copy omits the type and query_id the event form carries.
Show child attributes
type?stringEvent form only.
query_id?stringEvent form only.
n_steps?integerReasoning steps the turn ran.
n_tool_calls?integerHow many calls the whole turn made.
by_category?objectTool calls tallied by category.
total_hits?integerRetrieved items across all calls, before dedup.
duration_ms?integerWall time for the whole turn.
cache_read_tokens?integerInput tokens served from the prompt cache.
cache_write_tokens?integerInput tokens written into the prompt cache.