Skip to main content
POST
Error

Authorizations

X-API-Key
string
header
required
X-Tenant-Id
string
header
required

Body

application/json

Natural-language description of the runs, traces or threads to find, at most 2000 UTF-8 bytes.

Required string length: 1 - 2000
Example:

"threads where the agent did not complete the task and spent more than $1"

project_ids
string<uuid>[]
required

Tracing project UUIDs used to interpret the search. Send the same projects to the query API.

Minimum array length: 1
Example:
allow_clarification
boolean

When true, an ambiguous search returns clarification options instead of a single plan. Defaults to false.

scope
enum<string>

Query API to plan for: runs, traces or threads. When omitted, it is inferred from the search and defaults to traces.

Available options:
runs,
traces,
threads

Response

OK

clarification
object

Interpretations to choose from. Returned only when allow_clarification is true and the search is ambiguous; no other fields are set.

filter
string

Filter expression for the query API's filter parameter. Omitted when there is none.

max_start_time
string<date-time>

Upper bound on start time (RFC 3339, UTC) for the query API's max_start_time parameter. Omitted when the search names no end; keep your own time range.

min_start_time
string<date-time>

Lower bound on start time (RFC 3339, UTC) for the query API's min_start_time parameter. Omitted when the search names no start; keep your own time range.

scope
enum<string>

Query API to send the plan to: runs, traces or threads.

Available options:
runs,
traces,
threads
sem_filter
string | null

Plain-language criterion for the query API's sem_filter parameter, matched against conversation messages. Null when the search has no conversational criterion.

thread_filter
string

Filter expression for the threads query API's thread_filter parameter. Omitted when there is none.

trace_filter
string

Filter expression for the query API's trace_filter parameter. Omitted when there is none.

tree_filter
string

Filter expression for the query API's tree_filter parameter. Omitted when there is none.