> ## 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. # Discover what the trace filter fields hold > What the trace filter fields actually hold in THIS project, which the filter language's own reference deliberately does not carry: values are tenant data, they move under you, and reading them all costs about thirty aggregate queries. Two answers from one door. Without `field` you get the discovery payload: every facet this project has, each with its top values and counts, plus the range bounds for the numeric ones. With `field` you get one field's values, paged, filtered by `prefix`. The values are cached and refreshed in the background, so a cold project answers `pending: true` with the payload it has; call again shortly for the computed one. Use it whenever you are unsure how a value is spelled. `GET /api/v1/query/reference` lists the fields and their fixed vocabularies; only this endpoint knows the open ones. ## OpenAPI ````yaml GET /api/traces/facets 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/facets: get: tags: - Traces summary: Discover what the trace filter fields hold description: >- What the trace filter fields actually hold in THIS project, which the filter language's own reference deliberately does not carry: values are tenant data, they move under you, and reading them all costs about thirty aggregate queries. Two answers from one door. Without `field` you get the discovery payload: every facet this project has, each with its top values and counts, plus the range bounds for the numeric ones. With `field` you get one field's values, paged, filtered by `prefix`. The values are cached and refreshed in the background, so a cold project answers `pending: true` with the payload it has; call again shortly for the computed one. Use it whenever you are unsure how a value is spelled. `GET /api/v1/query/reference` lists the fields and their fixed vocabularies; only this endpoint knows the open ones. operationId: getApiTracesFacets parameters: - in: query name: field schema: type: string minLength: 1 maxLength: 512 - in: query name: prefix schema: type: string maxLength: 512 - in: query name: limit schema: type: integer minimum: 1 maximum: 1000 default: 50 - in: query name: offset schema: type: integer minimum: 0 default: 0 - in: query name: startDate schema: type: string - in: query name: endDate schema: type: string responses: '200': description: >- Without `field`, every facet the project has with its top values and whether the payload is still being computed. With `field`, that field's values and counts plus the distinct total and whether more remain. content: application/json: schema: anyOf: - type: object properties: facets: type: array items: type: object properties: key: type: string kind: type: string enum: - categorical - range - dynamic_keys label: type: string group: type: string required: - key - kind - label - group additionalProperties: true pending: type: boolean description: >- True when the payload is still being computed and what you have is the last committed one, possibly empty. Call again shortly. required: - facets - pending - type: object properties: values: type: array items: type: object properties: value: type: string label: type: string count: type: number required: - value - count total: type: number description: >- Distinct values the field holds in the window, before paging. hasMore: type: boolean required: - values - total - hasMore '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 '403': description: >- The field is an attribute key and this project hides captured input or output, so its values are not listed. content: application/json: schema: type: object properties: error: type: string const: trace_attribute_values_withheld message: type: string trace: type: string required: - error - message '422': description: >- The query did not name a facet with values to list. `fields` names the offending parameter and each reason carries what was received and what exists. content: application/json: schema: type: object properties: error: type: string const: validation_error message: type: string target: type: string const: query fields: type: array items: type: string reasons: type: array items: type: object properties: code: type: string meta: type: object properties: field: type: string type: type: string message: type: string received: type: string expected: type: array items: type: string required: - code trace: type: string required: - error - message - target - fields - reasons '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. ````