> ## 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 both query languages > Describes both query languages in one payload: LangWatchQL (SQL over the analytics views) with its schema, limits and endpoints, and the trace filter (a Lucene-flavored string over the trace list) with its syntax, its fields and their static value vocabularies, and the open-ended attribute namespaces. It also carries worked examples in both languages and a table saying which language answers which kind of question. Every example is checked against the real validator and the real translator before it ships, so a published example parses and compiles; whether THIS key can run one is its own `available` flag. Pure: it reads the catalogs and this key's own permissions, never the project's traces, so it answers from memory rather than from the database. It answers `Cache-Control: private, no-store`, because the document is shaped by the calling credential: `available`, the embedded schema and the gated columns all differ between keys, and a cache keyed on the URL or the project would replay one key's document to another. Ask for it again rather than storing it. The values a field actually holds change under you and are a separate call — `GET /api/traces/facets`. An example this key cannot run is listed with `available: false` and keeps its `requires.gates`, so a caller can see which permission it needs. Any credential for the project may read it. The trace filter half is the traces family's vocabulary, so a key scoped to `traces:view` alone is answered rather than refused; for that key the LangWatchQL half arrives with `lwql.enabled: false` and an empty schema. `GET /api/v1/query/schema` is stricter and refuses that key outright, which is why this document withholds the catalog rather than repeating it. ## OpenAPI ````yaml GET /api/v1/query/reference 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/v1/query/reference: get: tags: - Query summary: Discover both query languages description: >- Describes both query languages in one payload: LangWatchQL (SQL over the analytics views) with its schema, limits and endpoints, and the trace filter (a Lucene-flavored string over the trace list) with its syntax, its fields and their static value vocabularies, and the open-ended attribute namespaces. It also carries worked examples in both languages and a table saying which language answers which kind of question. Every example is checked against the real validator and the real translator before it ships, so a published example parses and compiles; whether THIS key can run one is its own `available` flag. Pure: it reads the catalogs and this key's own permissions, never the project's traces, so it answers from memory rather than from the database. It answers `Cache-Control: private, no-store`, because the document is shaped by the calling credential: `available`, the embedded schema and the gated columns all differ between keys, and a cache keyed on the URL or the project would replay one key's document to another. Ask for it again rather than storing it. The values a field actually holds change under you and are a separate call — `GET /api/traces/facets`. An example this key cannot run is listed with `available: false` and keeps its `requires.gates`, so a caller can see which permission it needs. Any credential for the project may read it. The trace filter half is the traces family's vocabulary, so a key scoped to `traces:view` alone is answered rather than refused; for that key the LangWatchQL half arrives with `lwql.enabled: false` and an empty schema. `GET /api/v1/query/schema` is stricter and refuses that key outright, which is why this document withholds the catalog rather than repeating it. operationId: getApiV1QueryReference responses: '200': description: >- The LangWatchQL schema and limits, the trace filter's syntax and fields, worked examples in both languages, and which language answers which kind of question. content: application/json: schema: type: object properties: version: type: string lwql: type: object properties: enabled: type: boolean schema: type: object properties: database: type: string views: type: array items: type: object properties: name: type: string description: type: string grain: type: string joinKeys: type: array items: type: string timeColumn: type: string freshness: type: string columns: type: array items: type: object properties: name: type: string type: type: string description: type: string unit: type: - string - 'null' enum: - ms - USD - tokens - tokens/s - null gates: type: array items: type: string enum: - input - output - costs available: type: boolean required: - name - type - description - unit - gates - available exampleSql: type: string required: - name - description - grain - joinKeys - timeColumn - freshness - columns - exampleSql functions: type: array items: type: string appFunctions: type: array items: type: object properties: name: type: string signature: type: string description: type: string kind: type: string enum: - extraction - eval returns: type: string encoding: type: string enum: - text - json keyKind: type: string enum: - trace - thread - span - text cap: type: integer exclusiveMinimum: 0 gates: type: array items: type: string enum: - input - output - costs available: type: boolean exampleSql: type: string required: - name - signature - description - kind - returns - encoding - keyKind - cap - gates - available - exampleSql required: - database - views - functions - appFunctions limits: type: object properties: maxStatementLength: type: number maxRowsReturned: type: number maxResultBytes: type: number maxExecutionTimeSeconds: type: number pagination: type: string required: - maxStatementLength - maxRowsReturned - maxResultBytes - maxExecutionTimeSeconds - pagination endpoints: type: array items: type: object properties: method: type: string enum: - GET - POST path: type: string description: type: string required: - method - path - description required: - enabled - schema - limits - endpoints traceFilter: type: object properties: syntax: type: string fields: type: array items: type: object properties: name: type: string label: type: string valueType: type: string enum: - categorical - range - text - existence group: type: - string - 'null' facetable: type: boolean knownValues: type: array items: type: string required: - name - label - valueType - group - facetable - knownValues dynamicPrefixes: type: array items: type: object properties: prefix: type: string label: type: string description: type: string aliases: type: array items: type: string required: - prefix - label - description - aliases endpoints: type: array items: type: object properties: method: type: string enum: - GET - POST path: type: string description: type: string required: - method - path - description required: - syntax - fields - dynamicPrefixes - endpoints examples: type: array items: type: object properties: id: type: string title: type: string intent: type: string enum: - triage - cost - latency - quality - conversations - discovery - export language: type: string enum: - lwql - trace-filter tags: type: array items: type: string text: type: string parameters: type: array items: type: object properties: name: type: string type: type: string description: type: string required: - name - type - description requires: type: object properties: gates: type: array items: type: string enum: - input - output - costs functions: type: array items: type: string required: - gates - functions available: type: boolean notes: type: string required: - id - title - intent - language - tags - text - parameters - requires - available decisionTable: type: array items: type: object properties: when: type: string use: type: string why: type: string required: - when - use - why required: - version - lwql - traceFilter - examples - decisionTable '400': description: Bad Request content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message 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. ````