# Fetch the recorded trace for a query turn

`GET /queries/{id}/trace`

:::code-group
```bash title="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 title="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 title="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 title="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 title="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 title="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 title="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
```
:::

:::code-group
```json title="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
  }
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | - |  |

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

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version?` | `string` | `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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | - | Query turn id. |

#### Response

`200` — The trace document

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps?` | `object[]` | - | The turn's reasoning steps, in the order they ran. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `step_id?` | `string` | - | Identifies the step within the turn. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `commentary?` | `string` | - | The model's own one-line account of what this step is doing. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code?` | `string` | - | The source string alone, as later rows store it. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `calls?` | `object[]` | - | The tool calls this step made. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fn?` | `string` | - | Name of the function this call invoked. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `category?` | `string` | - | Which family the tool belongs to, as tallied in the rollup's by_category. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `args?` | `object` | - | Compact, redacted summary of the call's arguments. The key set is tool-specific and deliberately open. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `result?` | `any` | - | Compact summary of the call's result (never the payload). The shape varies by category and is runtime-extensible. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `duration_ms?` | `integer` | - | Wall time for this one call. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ok?` | `boolean` | - | Whether the call succeeded. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `score_space?` | `string` | - | Which scoring space the returned scores live in, for calls that retrieve. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `error?` | `string` | - | Failure detail. Set when ok is false. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strategy?` | `object` | - | The retrieval approach the step picked. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind?` | `string` | - | Strategy family, e.g. artifacts_first. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fns?` | `string[]` | - | Tool functions the strategy calls. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` | - | Display label for the strategy. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope?` | `string[]` | - | Context ids the strategy searched. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens_in?` | `integer` | - | The step's input tokens. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens_out?` | `integer` | - | The step's output tokens. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decide_ms?` | `integer` | - | Time spent choosing what to do. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `execute_ms?` | `integer` | - | Time spent running the tool calls it chose. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens_in_cached?` | `integer` | - | Input tokens served from the prompt cache. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens_in_cache_write?` | `integer` | - | Input tokens written into the prompt cache. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens_in_fresh?` | `integer` | - | Input tokens neither cached nor cache-written. |
:::
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type?` | `string` | - | Event form only. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query_id?` | `string` | - | Event form only. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `n_steps?` | `integer` | - | Reasoning steps the turn ran. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `n_tool_calls?` | `integer` | - | How many calls the whole turn made. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `by_category?` | `object` | - | Tool calls tallied by category. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `total_hits?` | `integer` | - | Retrieved items across all calls, before dedup. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `duration_ms?` | `integer` | - | Wall time for the whole turn. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cache_read_tokens?` | `integer` | - | Input tokens served from the prompt cache. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cache_write_tokens?` | `integer` | - | Input tokens written into the prompt cache. |
:::

## Related pages

- [Run one KnowQL query turn](./data-plane-query-run-one-knowql-query-turn.md)
- [Fetch one query (turn)](./data-plane-query-fetch-one-query-turn.md)
- [Cancel an in-progress query turn](./data-plane-query-cancel-an-in-progress-query-turn.md)
- [Stream a query turn's events (SSE)](./data-plane-query-stream-a-query-turns-events-sse.md)
- [Record thumbs-up/down feedback on a query turn](./data-plane-query-record-thumbs-updown-feedback-on-a-query-turn.md)
- [List the selectable query models](./data-plane-query-list-the-selectable-query-models.md)
- [List project-wide query sessions (newest first)](./data-plane-query-list-project-wide-query-sessions-newest-first.md)
- [Get a session with its queries (conversation order)](./data-plane-query-get-a-session-with-its-queries-conversation-order.md)
- [Delete a session and its queries](./data-plane-query-delete-a-session-and-its-queries.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.