> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cancel a search
> Stop a search. A cancelled search costs 0.
The response is `202` with `state: cancelled` when this request stopped the search.
It is `200` with the current state when the search had already ended, for example
on a second cancel.
Default `rate-limit` is 300 requests per minute, shared by the read, events, and cancel routes.
## OpenAPI
````yaml /openapi-specs/2025-11-01/agent_search.yaml post /agent/searches/{search_id}/cancel
openapi: 3.0.3
info:
title: Agent Search API
version: '2025-11-01'
description: >
The Agent Search API (beta) takes a question in plain words and returns the
matching
people, companies or jobs, each with the reasons it matches. You send the
question to `POST /agent/searches`. An agent searches the
Crustdata datasets in the background, picks the columns of the answer, and
checks each
row against the requirements it read in your question.
A search runs for tens of seconds to a few minutes. Read it with
`GET /agent/searches/{search_id}` until `state` is `succeeded`, `failed` or
`cancelled`,
or stream its events with `Accept: text/event-stream`.
All requests require a valid API key passed via the `Authorization` header
as a Bearer
token and an `x-api-version` header set to `2025-11-01`.
servers:
- url: https://api.crustdata.com
description: Production API server
security:
- bearerAuth: []
tags:
- name: Agent Search APIs
description: Start, read, stream and cancel agent searches.
paths:
/agent/searches/{search_id}/cancel:
post:
tags:
- Agent Search APIs
summary: Cancel an agent search
description: >
Stop a search. A cancelled search costs 0.
The response is `202` with `state: cancelled` when this request stopped
the search.
It is `200` with the current state when the search had already ended,
for example
on a second cancel.
Default `rate-limit` is 300 requests per minute, shared by the read, events, and cancel routes.
operationId: cancelAgentSearch
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/SearchId'
responses:
'200':
headers:
X-Credits-Used:
$ref: '#/components/headers/XCreditsUsed'
description: The search had already ended.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSearchStarted'
examples:
already_ended:
summary: A second cancel
value:
search_id: 1318-ce76b669c98d42849a0c1d4239040e03
state: cancelled
'202':
headers:
X-Credits-Used:
$ref: '#/components/headers/XCreditsUsed'
description: This request stopped the search.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSearchStarted'
examples:
cancelled:
summary: A running search, stopped
value:
search_id: 1318-ce76b669c98d42849a0c1d4239040e03
state: cancelled
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/UnknownSearch'
'429':
$ref: '#/components/responses/RateLimited'
'503':
$ref: '#/components/responses/ReadUnavailable'
components:
parameters:
ApiVersion:
name: x-api-version
in: header
required: true
schema:
type: string
enum:
- '2025-11-01'
default: '2025-11-01'
example: '2025-11-01'
description: API version to use. This endpoint currently requires `2025-11-01`.
SearchId:
name: search_id
in: path
required: true
description: The `search_id` that the start returned.
schema:
type: string
example: 1318-07fcae93f67c961a96c8758766b2fea1
headers:
XCreditsUsed:
description: >-
Exact credits this request deducted, as a decimal string (for example
`0.9125`). On these routes, only the first read after a search ends
carries a value above `0`. Responses generated before a request reaches
the API, such as rate-limit `429`s, do not carry it.
schema:
type: string
example: '0.9125'
RetryAfter:
description: Seconds to wait before you try again.
schema:
type: string
example: '5'
schemas:
AgentSearchStarted:
type: object
description: A search id and its state at the moment of the response.
required:
- search_id
- state
properties:
search_id:
type: string
description: The id of the search. Use it on every other route.
example: 1318-07fcae93f67c961a96c8758766b2fea1
state:
$ref: '#/components/schemas/AgentSearchState'
AgentSearchState:
type: string
description: >-
The state of a search. `succeeded`, `failed` and `cancelled` are end
states. Every search in progress is `running` today. `queued` is not
returned today; a later release adds it for a search that waits in a
queue. Treat every state that is not an end state as in progress. This
enum is closed.
enum:
- queued
- running
- succeeded
- failed
- cancelled
example: running
ErrorResponse:
type: object
description: >-
The body of almost every error response. A `405` and a `404` on an
unknown path have another body.
required:
- error
properties:
error:
type: object
required:
- type
- message
- metadata
properties:
type:
type: string
example: invalid_request
message:
type: string
metadata:
type: array
description: >-
Empty, or `[{"retryable": true, "retry_after_seconds": N}]` on a
error that can clear if you try again later.
items:
type: object
properties:
retryable:
type: boolean
retry_after_seconds:
type: integer
responses:
Unauthorized:
description: The API key is missing or not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_api_key:
summary: No API key, or an API key that is not valid
value:
error:
type: unauthorized
message: Invalid API key in request.
metadata: []
UnknownSearch:
description: No search of your account has this `search_id`.
headers:
X-Credits-Used:
$ref: '#/components/headers/XCreditsUsed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unknown_search:
summary: The search_id is not one of yours
value:
error:
type: not_found
message: Unknown search_id.
metadata: []
RateLimited:
description: >-
More than 300 requests in one minute on the read, events, and cancel
routes. This `429` has no `Retry-After` header: wait for the seconds in
`X-RateLimit-Reset`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
rate_limit:
summary: The rate limit is used up
value:
error:
type: rate_limit_error
message: >-
Rate limit exceeded for this endpoint. Please write to
gtm@crustdata.co.
metadata: []
ReadUnavailable:
description: >-
Agent Search did not answer, or the rows of an ended search are not
ready yet. Try again after `Retry-After` seconds. These messages come
from the api code and were not reproduced live.
headers:
X-Credits-Used:
$ref: '#/components/headers/XCreditsUsed'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
not_answered:
summary: Agent Search did not answer
value:
error:
type: service_unavailable
message: Agent Search did not answer. Try again in a few seconds.
metadata:
- retryable: true
retry_after_seconds: 5
rows_not_ready:
summary: The rows of an ended search are not ready
value:
error:
type: service_unavailable
message: >-
The rows of this search are not ready. Try again in a few
seconds.
metadata:
- retryable: true
retry_after_seconds: 5
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key passed as a Bearer token in the `Authorization` header.
````
## Related topics
- [Agent Search API](https://docs.crustdata.com/agent-search-docs/overview.md)
- [Read a search](https://docs.crustdata.com/api-reference/agent-search-apis/read-an-agent-search.md)
- [Search](https://docs.crustdata.com/api-reference/web-apis/web-search.md)
- [Pricing](https://docs.crustdata.com/general/pricing.md)
- [Cancel a discovery watch](https://docs.crustdata.com/api-reference/watch-apis/cancel-a-discovery-watch.md)