Skip to main content
POST
Search spans

Authorizations

​
x-api-key
string
header
required

Headers

​
x-selected-account-id
string | null
​
x-project-id
string | null

Query Parameters

​
allow_partial_results
boolean
default:false

Return however many spans fit the server byte budget instead of a 400 SEARCH_RESULT_TOO_LARGE, reporting the rest through has_more plus next_cursor going forward or prev_cursor going back. A search that spends its time budget before the page fills also returns what it found, with search_status partial, searched_through and a next_cursor that resumes from there. Send it only if the client reads has_more, because under it a page shorter than limit no longer means the end of the list. Honored by the tracing service on either of its storage engines. Accounts still served by the legacy trace store ignore it and page by item count, where a short page still means the end of the list.

​
starting_after
string | null
​
ending_before
string | null
​
limit
integer
default:100
Required range: 1 <= x <= 10000
​
sort_by
string | null
​
sort_order
enum<string> | null
default:asc
Available options:
asc,
desc
​
from_ts
string<date-time> | null

The starting (oldest) timestamp in ISO format.

​
to_ts
string<date-time> | null

The ending (most recent) timestamp in ISO format.

Body

application/json
​
parents_only
boolean | null

Only fetch spans that are the top-level (ie. have no parent_id)

​
span_ids
string[] | null

Filter by span IDs

​
trace_ids
string[] | null

Filter by trace IDs. The combined count of trace_ids, span_ids, excluded_span_ids, excluded_trace_ids, parent_ids, and (trace_id, span_id) pairs (each pair counting 2) may not exceed 10000. A request over that returns 422.

​
excluded_span_ids
string[] | null

List of span IDs to exclude from results

​
excluded_trace_ids
string[] | null

List of trace IDs to exclude from results

​
spans
SpanRef · object[] | null

Filter by exact (trace_id, span_id) identity. Unlike span_ids, a pair never matches a same-id span from another trace. ANDs with span_ids when both are set.

​
excluded_spans
SpanRef · object[] | null

List of (trace_id, span_id) identities to exclude from results. Unlike excluded_span_ids, a pair never excludes a same-id span from another trace. Takes precedence over excluded_span_ids when both are set.

​
group_id
string | null

Filter by group ID

​
parent_ids
string[] | null

Filter to the direct children of any of these parent span IDs

​
names
string[] | null

Filter by trace/span name

​
statuses
enum<string>[] | null

Filter on span status

Available options:
SUCCESS,
ERROR,
CANCELED
​
types
enum<string>[] | null
Available options:
TEXT_INPUT,
TEXT_OUTPUT,
COMPLETION_INPUT,
COMPLETION,
KB_RETRIEVAL,
KB_INPUT,
RERANKING,
EXTERNAL_ENDPOINT,
PROMPT_ENGINEERING,
DOCUMENT_INPUT,
MAP_REDUCE,
DOCUMENT_SEARCH,
DOCUMENT_PROMPT,
CUSTOM,
CODE_EXECUTION,
DATA_MANIPULATION,
EVALUATION,
FILE_RETRIEVAL,
KB_ADD_CHUNK,
KB_MANAGEMENT,
GUARDRAIL,
OUTPUT_GUARDRAIL,
TRACER,
AGENT_TRACER,
AGENT_WORKFLOW,
STANDALONE
​
search_texts
string[] | null

Case-insensitive text search across span name, input, output, and metadata. A single-word term of ASCII letters and digits matches as a whole word in input, output, and metadata, and as a substring of the name. A term of up to 8 such words matches as a contiguous phrase whose words each appear as whole words. All other terms (punctuated, non-ASCII, longer) match as substrings, where mid-word fragments match and an inflected form such as a plural matches only where it appears literally. Wrapping a term in double quotes makes it a phrase: the quotes mark the phrase and are never matched, a backslash escapes a quote or a backslash inside them, the phrase must appear contiguously inside one searched value (the input, the output, or the metadata), a phrase of up to 8 ASCII letter-and-digit words additionally requires each of those words to appear there as a whole word, and a UUID-shaped phrase stays a text search. A term whose quote is unterminated or left unescaped mid-term is matched literally, quotes included. Multiple terms are ANDed, and UUID-shaped terms match trace IDs instead. A span must match every non-UUID term, and each term may match any of the searched fields. UUID matches are ORed onto the text match. Each term must be at least 2 characters, measured between the quotes and ignoring outer whitespace for a phrase, and at most 10 terms are supported. For exact trace ID lookup, use the trace_ids filter. The tracing service runs on either ClickHouse or Postgres, and the two engines match differently. On Postgres deployments the whole-word match uses the simple text-search parser, which keeps hosts, e-mail addresses, file paths, version strings, hyphenated compounds, URLs and query strings as single words (https://x.com/path?q=1 yields x.com/path?q=1, x.com and /path?q=1, never path, q or 1; user@example.com and v1.2.3 are one word each; gpt-4o yields the compound and its parts), whereas ClickHouse deployments split on every non-alphanumeric ASCII byte. A single word inside such a value is a whole-word hit on ClickHouse and a miss on Postgres; the substring forms behave identically on both. On Postgres deployments a value over 80000 bytes has only its first 20000 characters indexed for whole-word matching; text past that is reachable only by the substring forms. Words longer than 2047 bytes are matched as substrings, never as whole words. Case folding of non-ASCII text follows the database's LC_CTYPE on Postgres deployments, for the whole-word index, the quoted-phrase and substring forms and the word-boundary check alike; under a C-locale database non-ASCII letters are not folded. ASCII folds everywhere. Input and output behave identically on both engines. A substring-form term, or a text-filtered metrics request, reads every row of the time window that survives the other filters. A term that matches too many rows in the window is refused by the tracing service as QUERY_TOO_BROAD, at an engine-specific threshold, and on Postgres deployments a read whose sorts or hashes, the text candidate sets included, outgrow the deployment's work memory and its temp-file bound is refused as QUERY_TEMP_FILE_LIMIT_EXCEEDED, a code ClickHouse deployments never return and one a read without text can also earn. This API relays either refusal as a 400 carrying the tracing service's detail, never as a page from the legacy trace store, and an export's refusal is reported as the failed export's reason on the export status, not on the POST. On Postgres deployments each term is counted on its own, in every class (whole word, phrase and substring alike) and on every read that carries text, and is refused when it alone matches more than 50000 rows of the window that survive the other filters, with or without assessment_types. On ClickHouse deployments the refusal is the candidate-set cap, a deployment-configured limit counted over the matches of all terms together: a search page bounds its candidates to the page, so there the cap is a backstop rather than a limit a common term meets; metrics and by-span resolve every match and can trip it; and an export runs under its own 2000000-row set cap on every request, assessment_types included. Accounts still served by the legacy trace store match differently until migrated: every term matches as stemmed whole words (so inflected forms match and multi-word terms match word-adjacent), only input and output are searched, the 2-character minimum is not enforced, quoting a term changes nothing (the quotes are stripped and a multi-word term is already matched word-adjacent), and characters like :, |, or ! inside a term may be interpreted as query operators or cause an error.

​
extra_metadata
Extra Metadata · object | null

Filter on custom metadata: each key must equal its value, or any value of an array, and keys are ANDed. On the ClickHouse read path $or and $and also compose nested groups of predicates. On Postgres a $-prefixed key is an ordinary metadata key matched literally. Array values match element-wise; a negative zero inside an array equals zero on Postgres-served accounts and not on ClickHouse-served ones.

​
application_variant_ids
string[] | null

Filter by application variant IDs

​
assessment_types
string[] | null

Filter to spans that have at least one assessment of these types

​
acp_types
string[] | null

Filter by ACP types

​
agentex_agent_names
string[] | null

Filter by Agentex agent names

​
agentex_agent_ids
string[] | null

Filter by Agentex agent IDs

​
obs_trace_ids
string[] | null

Filter to the business spans that executed in any of these observability traces (the obs-to-business reverse lookup). Each id must be 32 lowercase hex characters. Served only by the sgp-traces service, so a request using this filter against an account still on the legacy store returns 422 rather than silently ignoring it.

​
obs_span_ids
string[] | null

Filter to the business spans that executed in any of these observability spans. Each id must be 16 lowercase hex characters. A W3C span id is unique per trace only, so combine with obs_trace_ids for exact identity, the same looseness span_ids carries versus the spans pair filter. ANDs with obs_trace_ids when both are set. Served only by the sgp-traces service, so a request using this filter against an account still on the legacy store returns 422 rather than silently ignoring it.

​
min_duration_ms
integer | null

Minimum span duration in milliseconds (inclusive). Matched on completed duration, so a span with no end time is not reliably returned: fetch it by its own id or in its trace's span list.

​
max_duration_ms
integer | null

Maximum span duration in milliseconds (inclusive). Matched on completed duration, so a span with no end time is never returned: fetch it by its own id or in its trace's span list.

Response

Successful Response

Span search page carrying sgp-traces' opaque pagination cursors.

Accounts still served by the legacy trace store keyset-paginate on the span id and leave these unset, except that a page the legacy store serves as a fallback for a tracing-service account, or in continuation of a fallback cursor, carries cursors this API mints so later pages stay on the legacy store. The tracing service, on either of its storage engines, returns opaque cursors that clients must round-trip.

​
items
Items · object[]
required
​
total
integer
required

Not computed for span search and always 0: results are keyset-paginated, so page with has_more and the cursors instead.

​
has_more
boolean
required

Whether more items remain in the direction of travel. Under allow_partial_results this is the only end-of-list signal, since the byte or time budget can serve a page shorter than limit with rows still left.

​
object
string
default:list
Allowed value: "list"
​
limit
integer
default:100

The maximum number of items to return.

​
next_cursor
string | null

Pass as starting_after to fetch the next page. None when there is no next page.

​
prev_cursor
string | null

Pass as ending_before to fetch the previous page. None when on the first page.

​
window_truncated
boolean | null

True when the requested window exceeded the 90 day maximum and was clamped, so results cover only effective_from_ts..effective_to_ts. null when no clamp occurred.

​
effective_from_ts
string<date-time> | null

Resolved start of the searched window. null when no clamp occurred.

​
effective_to_ts
string<date-time> | null

Resolved end of the searched window. null when no clamp occurred.

​
search_status
enum<string> | null

complete when the page holds every match from the request's position to its last item or the end of the window. partial when an allow_partial_results search spent its time budget first: the page holds every match up to searched_through, and next_cursor resumes from there. null on accounts still served by the legacy trace store.

Available options:
complete,
partial
​
searched_through
string<date-time> | null

On a partial page, the start_timestamp the search covered up to in its scan order, oldest first for a descending sort. null on a complete page.