> ## 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 ## OpenAPI ````yaml POST /api/traces/search openapi: 3.1.0 info: title: LangWatch API version: 1.0.0 description: LangWatch openapi spec servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/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: type: object properties: topics.topics: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string topics.subtopics: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.user_id: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.thread_id: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.customer_id: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.labels: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.key: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.value: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string metadata.prompt_ids: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string traces.origin: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string traces.error: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string traces.name: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string spans.type: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string spans.model: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.evaluator_id: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.evaluator_id.guardrails_only: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.evaluator_id.has_passed: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.evaluator_id.has_score: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.evaluator_id.has_label: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.passed: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.score: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.state: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string evaluations.label: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string events.event_type: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string events.metrics.key: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string events.metrics.value: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string events.event_details.key: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string annotations.hasAnnotation: anyOf: - type: array items: type: string - type: object additionalProperties: type: array items: type: string - type: object additionalProperties: type: object additionalProperties: type: array items: type: string additionalProperties: false default: {} traceIds: type: array items: type: string negateFilters: type: boolean pageOffset: type: number 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. pageSize: type: integer exclusiveMinimum: 0 groupBy: type: string sortBy: type: string sortDirection: type: string updatedAt: type: number scrollId: type: - string - 'null' startDate: anyOf: - type: number - type: string endDate: anyOf: - type: number - type: string format: type: string enum: - digest - json description: >- Output format: 'digest' (AI-readable trace digest) or 'json' (full raw data) includeSpans: type: boolean description: >- When true, fetches full span data for each trace. Useful for bulk export. Default false. llmMode: type: boolean dateField: type: string enum: - occurred - updated 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. from: type: string enum: - traces default: traces description: >- Entity root to read from. Only 'traces' is supported today; defaults to 'traces' when omitted. select: type: array items: type: string minLength: 1 maxLength: 256 minItems: 1 maxItems: 200 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. 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: type: number 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. updatedThrough: type: number 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. required: - totalHits schema: 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 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. required: - traces - pagination '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error 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. ````