Search traces

Search traces for a project

POST /api/v1/traces/search

Python

Python

import requests

url = "https://app.langwatch.ai/api/v1/traces/search"

payload = {
    "startDate": 123,
    "endDate": 123
}
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

200

{
  "traces": [
    "<unknown>"
  ],
  "pagination": {
    "totalHits": 123,
    "scrollId": "<string>",
    "skipped": 123,
    "updatedThrough": 123
  },
  "schema": {
    "from": "<string>",
    "columns": [
      {
        "path": "<string>",
        "type": "<string>",
        "collection": true
      }
    ]
  }
}

The filter field takes the LangWatch filter language. See Filtering traces for the syntax.

status:error
-status:error
evaluatorVerdict:fail
has:feedback
has:annotation
event:thumbs_up_down

has:feedback matches traces with thumbs_up_down feedback, recorded through POST /api/events/track or the SDK. has:annotation matches traces with an annotation, including ones created through POST /api/annotations/trace/{id}. The annotation reaches trace search a moment after it is saved. event:<name> matches traces carrying an event with that name.

Prefer filter over the older filters map. In that map, evaluation fields are keyed by monitor ID: {"evaluations.passed": {"<monitorId>": ["false"]}}. A flat list such as {"evaluations.passed": ["false"]} is rejected with 422. To find failed evaluations across every evaluator, send "filter": "evaluatorVerdict:fail".

Authorizations

X-Auth-Token · string · header · required

Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.

Body

application/json

startDate · number string · required

endDate · number string · required

query · string

filters · object

Show child attributes

traceIds · string[]

negateFilters · boolean

excludeOrigins · string[]

pageOffset · number

Removed. Offset pagination is no longer supported and any value other than 0 is rejected. Page with the scrollId returned by the previous response instead. The field remains on the schema so that sending it produces an explanatory error rather than being silently discarded.

pageSize · integer

Required range: x <= 9007199254740991

groupBy · string

sortBy · string

sortDirection · string

updatedAt · number

scrollId · string | null

filter · string

A trace filter string in the same language the Trace Explorer's search bar speaks — status:error AND model:gpt-*, trace.attribute.langwatch.user_id:alice, a quoted phrase for free text. Combined with filters/query/traceIds rather than replacing them, so every condition sent must hold. A malformed filter, or one naming a field the language does not have, is a 422 that names the filter field.

Maximum string length: 4000

format · enum<string>

Output format: 'digest' (AI-readable trace digest) or 'json' (full raw data)

Available options: digest, json

includeSpans · boolean

When true, fetches full span data for each trace. Useful for bulk export. Default false.

llmMode · boolean

dateField · enum<string> · default: occurred

Which timestamp the startDate/endDate window filters on. 'occurred' (default) selects traces by when they happened. 'updated' selects traces by when they were last modified — use this for incremental ETL ('give me everything changed since my last pull'), since a trace can occur long before it gains a later evaluation or annotation.

Available options: occurred, updated

from · enum<string> · default: traces

Entity root to read from. Only 'traces' is supported today; defaults to 'traces' when omitted.

Available options: traces

select · string[]

Flat list of dotted-path columns to project, e.g. ['trace_id','metadata.user_id','events.type','evaluations.score']. Paths group by root in the response: scalar fields stay top-level, 'metadata.' nests under a metadata object, and 'events.'/'annotations.'/'evaluations.' return as nested arrays (one row per trace). When present, the response gains a top-level 'schema' field describing the resolved columns. When omitted, the response is unchanged from the legacy shape.

Required array length: 1 - 200 elements

Required string length: 1 - 256

Response

200

application/json

Matching traces with pagination

traces · any[] · required

pagination · object · required

Show child attributes

schema · object

Present only when 'select' is provided. Describes the resolved columns — the dotted path, its value type, and whether it belongs to a nested child collection — so callers can pre-allocate a typed reader.

Show child attributes