# Run one KnowQL query turn

`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`

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

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

```json title="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

| 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. |

#### Body

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ask` | `string` | - | The natural-language question |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope?` | `string[]` | - | Context slugs/UUIDs. New session only; pinned for the session's life. A scope may not mix work and search contexts. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `session_id?` | `string` | - | Continue an existing session |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `previous_query_id?` | `string` | - | Continue the session this query belongs to |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workflow?` | `string` | - | Search workflow for this turn. Ignored for work contexts, which always run the work runtime. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `system_prompt?` | `string` | - | Instructions pinned to a new session |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `guardrails?` | `string` | - | Guardrails pinned to a new session |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shape?` | `object` | - | JSON Schema subset for structured output; result in output_json |

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `models?` | `string[]` | - | Ordered fallback list, tried in turn. Takes precedence over model. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tools?` | `string[]` | - | Tool names the turn may call. New session only; pinned for the session's life. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stream?` | `boolean` | - | SSE streaming. Mutually exclusive with background. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `boolean` | - | Fire-and-forget: 202 + in_progress query; poll GET /queries/id. Mutually exclusive with stream. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `timeout_seconds?` | `integer` | - | May only LOWER the 15-minute (900s) cap |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max_steps?` | `integer` | - | Cap the agent's tool-loop steps for this turn |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `thinking_level?` | `string` | - | Gemini reasoning depth. Default low. Gemini-backed workflows only; ignored for search_cc. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `compose?` | `boolean` | - | Set false to skip synthesis, the same as retrieval_only. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `retrieval_only?` | `boolean` | - | Skip synthesis; return retrieved hits in output_json |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pointers_only?` | `boolean` | - | Skip synthesis; return just pointers in output_json |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chunks_only?` | `boolean` | - | Retrieval-only, narrowed to chunks |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `artifacts_only?` | `boolean` | - | Retrieval-only, narrowed to artifacts |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max_retrieved?` | `integer` | - | Cap the item count for retrieval-only turns |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max_retrieved_chars?` | `integer` | - | Cap per-item verbatim text length for retrieval-only turns |

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

#### Response

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

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

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

Turn id, `qry_<uuid>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `object` | `string` | - | Always query, so a caller can tell this document apart from a session. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `session_id` | `string` | - | The session this turn belongs to. A turn that started a new one names it here. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model?` | `string \| null` | - | The model that actually answered. Null before the turn resolves one. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `created` | `integer` | - | Unix seconds |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `string` | - | Where the turn is in its lifecycle. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `error?` | `string \| null` | - | Failure detail. Set on a failed turn. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `previous_query_id?` | `string \| null` | - | The turn this one continues. Null on a session's first turn. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `comparison?` | `object[] \| null` | - | The sibling turns of the same Compare run. Null on a normal single query. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workflow?` | `string` | - | The workflow that turn ran. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query_id?` | `string` | - | That turn's id. Fetch it with GET /queries/id. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model?` | `string` | - | The model that answered it. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `feedback?` | `object \| null` | - | Thumbs-up/down recorded on this turn. Null until a caller submits some. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rating?` | `string` | - | Thumbs up or down. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `comment?` | `string \| null` | - | Free-text note. Null when none was given. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` | `object[]` | - | The stored message array (plain-text content). |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `role` | `string` | - | Who sent the message, e.g. user. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `string` | - | The message text. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `output` | `object[]` | - | Output items; assistant text is role, content:[type: output_text, text] |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `role` | `string` | - | Who produced it, e.g. assistant. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `object[]` | - | The item's content parts. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` | - | Part kind. output_text carries the answer. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | - | The text of this part. |
:::
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `output_json?` | `object \| null` | - | Present when a shape was used, or on a retrieval-only turn |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `citations` | `object[]` | - | What the answer was grounded in. Empty on a turn that cited nothing. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `source?` | `string` | - | Path of the cited corpus file, relative to the source-tree root. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `section_paths?` | `string[][]` | - | Heading paths within the source, when known. One inner array per cited section, outermost heading first. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pages?` | `integer[]` | - | 1-based page numbers, for sources that paginate. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `score?` | `number` | - | Retrieval score — how well this source answered the ask. Comparable only within one turn. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `grounding?` | `string` | - | The quoted span the answer rests on. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind?` | `string` | - | Which index the citation came out of, e.g. chunk or artifact. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `source_path?` | `string` | - | Work contexts — path of the artifact the fact was consolidated into. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query_id?` | `string` | - | Work contexts — the earlier turn the fact was learned from. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps?` | `string[]` | - | Work contexts — step ids within that earlier turn. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `artifact_name?` | `string` | - | Work contexts — name of the cited artifact. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sources?` | `string[]` | - | The documents a cited artifact was derived from. |
:::

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `thinking_level?` | `string \| null` | - | The thinking level this turn actually ran at. Null on the Claude-backed search_cc, which has no equivalent knob. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `object[]` | - | The turn's reasoning steps, reduced from its response.step events. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `step_id` | `string` | - | Identifies the step within the turn. Clients merge repeated events by it. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `string` | - | How far the step has got. |

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fns?` | `string[]` | - | Tool functions this step called. |

| 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 |
| --- | --- | --- | --- |
| `tool_calls?` | `object[]` | - | Per-call detail for the step's tool calls. |

:::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 |
| --- | --- | --- | --- |
| `code?` | `string` | - | The source string alone, as later rows store it. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trace_truncated?` | `object` | - | What a clamp shed from an oversized step event. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `truncated?` | `boolean` | - | Whether the clamp fired at all. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dropped_documents?` | `integer` | - | Retrieved documents shed from the event. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dropped_tool_calls?` | `integer` | - | How many calls the clamp discarded. |
:::

| 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 |
| --- | --- | --- | --- |
| `input_tokens?` | `integer` | - | Prompt tokens billed by this one step. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `output_tokens?` | `integer` | - | Completion tokens billed by this one step. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `total_tokens?` | `integer` | - | Prompt plus completion for this one step. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cum_input_tokens?` | `integer` | - | Turn-to-date input tokens, including this step. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cum_output_tokens?` | `integer` | - | Turn-to-date output tokens, including this step. |
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rollup?` | `object \| null` | - | End-of-turn counters. Null on a turn the runtime never closed. |

:::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. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `synthesis?` | `object \| null` | - | The answer completion's cost. Null on a turn that skipped synthesis, as retrieval-only turns do. |

:::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 |
| --- | --- | --- | --- |
| `status?` | `string` | - | How synthesis ended, e.g. completed. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens_in?` | `integer` | - | The completion's input tokens. |

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ms?` | `integer` | - | Wall time of the completion. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `answer_preview?` | `string` | - | Leading characters of the answer, for a progress display that has no full text yet. |

| 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 |
| --- | --- | --- | --- |
| `trace_ref?` | `string \| null` | - | Blob key of the persisted trace. Fetch the trace itself from GET /queries/id/trace. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | - | The turn's token totals. Embed and rerank bill on their own seam and are not counted here. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input_tokens` | `integer` | - | Input tokens the turn billed. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `output_tokens` | `integer` | - | Output tokens the turn billed. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `total_tokens` | `integer` | - | Input plus output tokens. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `runtime_ms` | `integer` | - | Wall time from turn start to terminal state. |

## Related pages

- [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)
- [Fetch the recorded trace for a query turn](./data-plane-query-fetch-the-recorded-trace-for-a-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.