Start a search

Start a search from a question in plain words. The body has one key, query.

The Accept request header picks the response:

• application/json (the default; */* or no Accept header gives the same) returns the search_id and the state of the search at that moment.
• text/event-stream returns the event stream of the search, from its first event to search.finished. The X-Search-Id response header carries the search_id, so you can resume on GET /agent/searches/{search_id}/events if the stream breaks.

Error responses are JSON whatever Accept says.

A start returns 202 with the new search_id and its state, which is running. If you send the same Idempotency-Key with the same query again, the response is 200 with the current state of the first search, and that search can already be over. Always read state from the body, not from the status code. Treat every state that is not succeeded, failed or cancelled as still in progress, because a later release adds queued.

Only POST is allowed on this path. A GET returns 405 with {"detail": "Method \"GET\" not allowed."}, and it counts toward the start limit.

The start costs nothing and returns X-Credits-Used: 0. The first read after the search ends charges it. Before a search begins, the API checks that your balance covers 8 credits for each search of your account that has no charge yet, this one included. The check takes no credits, and 8 credits is not the price of a search: a search usually costs much less.