Search traces

Search traces for a project

POST /api/traces/search

Python

Python

import requests

url = "https://app.langwatch.ai/api/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
      }
    ]
  }
}

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

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

groupBy · string

sortBy · string

sortDirection · string

updatedAt · number

scrollId · string | null

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