# Cancel an in-progress query turn

`POST /queries/{id}/cancel`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://{host}/api/queries/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>'
```

```python title="Python"
import requests

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

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

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

print(response.text)
```

```javascript title="JavaScript"
const options = {method: "POST", headers: {"Authorization": "Bearer <token>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>"}};

fetch("https://{host}/api/queries/{id}/cancel", 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}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  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}/cancel"

	req, _ := http.NewRequest("POST", 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.post("https://{host}/api/queries/{id}/cancel")
  .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}/cancel")

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

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="404"
{
  "message": "<string>",
  "code": "<string>"
}
```
:::

#### 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 (now cancelled) query

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

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