> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # Search traces > Search traces for a project The `filter` field takes the LangWatch filter language. See [Filtering traces](/docs/features/querying-your-data#filtering-traces) for the syntax. ```text theme={null} 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:` 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": {"": ["false"]}}`. A flat list such as `{"evaluations.passed": ["false"]}` is rejected with 422. To find failed evaluations across every evaluator, send `"filter": "evaluatorVerdict:fail"`. ## OpenAPI ````yaml POST /api/v1/traces/search openapi: 3.1.0 info: title: LangWatch API description: LangWatch openapi spec version: 1.0.0 servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/v1/traces/search: post: description: Search traces for a project operationId: postApiTracesSearch requestBody: required: true content: application/json: schema: type: object properties: query: type: string filters: default: {} type: object propertyNames: type: string enum: - topics.topics - topics.subtopics - metadata.user_id - metadata.thread_id - metadata.customer_id - metadata.labels - metadata.key - metadata.value - metadata.prompt_ids - traces.origin - traces.error - traces.name - spans.type - spans.model - evaluations.evaluator_id - evaluations.evaluator_id.guardrails_only - evaluations.evaluator_id.has_passed - evaluations.evaluator_id.has_score - evaluations.evaluator_id.has_label - evaluations.passed - evaluations.score - evaluations.state - evaluations.label - events.event_type - events.metrics.key - events.metrics.value - events.event_details.key - annotations.hasAnnotation additionalProperties: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string properties: topics.topics: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string topics.subtopics: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.user_id: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.thread_id: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.customer_id: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.labels: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.key: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.value: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string metadata.prompt_ids: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string traces.origin: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string traces.error: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string traces.name: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string spans.type: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string spans.model: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.evaluator_id: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.evaluator_id.guardrails_only: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.evaluator_id.has_passed: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.evaluator_id.has_score: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.evaluator_id.has_label: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.passed: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.score: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.state: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string evaluations.label: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string events.event_type: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string events.metrics.key: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string events.metrics.value: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string events.event_details.key: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string annotations.hasAnnotation: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string traceIds: type: array items: type: string negateFilters: type: boolean excludeOrigins: type: array items: type: string pageOffset: description: >- 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. type: number pageSize: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 groupBy: type: string sortBy: type: string sortDirection: type: string updatedAt: type: number scrollId: type: - string - 'null' startDate: type: - number - string endDate: type: - number - string filter: description: >- 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. type: string maxLength: 4000 format: description: >- Output format: 'digest' (AI-readable trace digest) or 'json' (full raw data) type: string enum: - digest - json includeSpans: description: >- When true, fetches full span data for each trace. Useful for bulk export. Default false. type: boolean llmMode: type: boolean dateField: default: occurred description: >- 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. type: string enum: - occurred - updated from: default: traces description: >- Entity root to read from. Only 'traces' is supported today; defaults to 'traces' when omitted. type: string enum: - traces select: description: >- 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. minItems: 1 maxItems: 200 type: array items: type: string minLength: 1 maxLength: 256 required: - startDate - endDate responses: '200': description: Matching traces with pagination content: application/json: schema: type: object properties: traces: type: array items: {} pagination: type: object properties: totalHits: type: number scrollId: type: string skipped: description: >- Number of traces dropped from this page because they failed to serialize. Present only when non-zero, so a caller can tell that traces.length is below the page size for a reason other than reaching the end of the result set. type: number updatedThrough: description: >- Only when dateField is 'updated'. Epoch milliseconds: the upper bound this scroll actually covered, which is at or before the endDate you asked for. The scroll reads every trace as of the moment it started, so anything written after that instant belongs to the next pull. Start your next incremental pull from this value — resuming from the endDate you requested would step over the difference and lose those traces. The bound is inclusive on both sides, so a trace last written at exactly this millisecond arrives in this pull and again in the next one: pulls are at-least-once, and applying them idempotently is what keeps that from becoming a duplicate. type: number required: - totalHits schema: description: >- 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. type: object properties: from: type: string columns: type: array items: type: object properties: path: type: string type: type: string collection: type: boolean required: - path - type - collection required: - from - columns required: - traces - pagination '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false security: - project_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.