> ## 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 datasets) with its schema, limits and endpoints, and the trace filter (a Lucene-flavoured 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 before it ships, so a published example parses; whether THIS key can run one is its own `available` flag. Pure: it reads the catalogues and this key's own permissions, never the project's traces, so it answers from memory rather than from the database. The document is shaped by the calling credential — `available`, the embedded schema and the gated columns all differ between keys — so never cache it beyond the key that asked for it. Ask 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 catalogue rather than repeating it. ## OpenAPI ````yaml GET /api/v1/query/reference 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/query/reference: get: tags: - Query summary: Discover both query languages description: >- Describes both query languages in one payload: LangWatchQL (SQL over the analytics datasets) with its schema, limits and endpoints, and the trace filter (a Lucene-flavoured 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 before it ships, so a published example parses; whether THIS key can run one is its own `available` flag. Pure: it reads the catalogues and this key's own permissions, never the project's traces, so it answers from memory rather than from the database. The document is shaped by the calling credential — `available`, the embedded schema and the gated columns all differ between keys — so never cache it beyond the key that asked for it. Ask 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 catalogue 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 functions: readOnly: true type: array items: type: string views: readOnly: true type: array items: type: object properties: name: type: string description: type: string grain: type: string joinKeys: readOnly: true type: array items: type: string timeColumn: type: - string - 'null' freshness: type: string columns: readOnly: true type: array items: type: object properties: name: type: string type: type: string description: type: string unit: type: - string - 'null' gates: readOnly: true type: array items: anyOf: - type: string enum: - input - output - costs - type: string enum: - organization:view - organization:manage - organization:delete - project:view - project:create - project:update - project:delete - project:manage - team:view - team:manage - analytics:view - analytics:create - analytics:update - analytics:delete - analytics:manage - cost:view - traces:view - traces:create - traces:update - traces:share - scenarios:view - scenarios:create - scenarios:update - scenarios:delete - scenarios:manage - annotations:view - annotations:create - annotations:update - annotations:delete - annotations:manage - evaluations:view - evaluations:create - evaluations:update - evaluations:delete - evaluations:manage - datasets:view - datasets:create - datasets:update - datasets:delete - datasets:manage - triggers:view - triggers:create - triggers:update - triggers:delete - triggers:manage - workflows:view - workflows:create - workflows:update - workflows:delete - workflows:manage - experiments:view - experiments:create - experiments:update - experiments:delete - experiments:manage - prompts:view - prompts:create - prompts:update - prompts:delete - prompts:manage - secrets:view - secrets:create - secrets:update - secrets:delete - secrets:manage - playground:view - playground:create - playground:update - playground:delete - playground:manage - ops:view - ops:manage - auditLog:view - virtualKeys:view - virtualKeys:create - virtualKeys:update - virtualKeys:delete - virtualKeys:rotate - virtualKeys:manage - virtualKeys:viewOtherPersonal - gatewayBudgets:view - gatewayBudgets:create - gatewayBudgets:update - gatewayBudgets:delete - gatewayBudgets:manage - gatewayProviders:view - gatewayProviders:update - gatewayProviders:manage - routingPolicies:view - routingPolicies:manage - gatewayGuardrails:view - gatewayGuardrails:attach - gatewayGuardrails:detach - gatewayGuardrails:manage - gatewayLogs:view - gatewayUsage:view - gatewayCacheRules:view - gatewayCacheRules:create - gatewayCacheRules:update - gatewayCacheRules:delete - gatewayCacheRules:manage - governance:view - governance:manage - ingestionSources:view - ingestionSources:create - ingestionSources:update - ingestionSources:delete - ingestionSources:manage - anomalyRules:view - anomalyRules:create - anomalyRules:update - anomalyRules:delete - anomalyRules:manage - complianceExport:view - activityMonitor:view - aiTools:view - aiTools:manage - webhookEndpoints:view - webhookEndpoints:manage - gatewaySpend:view - gatewaySpend:manage - langy:view - langy:create - langy:update - langy:delete - langy:manage - agentCache:view - agentCache:manage - featureFlags:manageExperiments - governanceCost:view - sso:view - sso:manage available: type: boolean required: - name - type - description - unit - gates - available additionalProperties: false exampleSql: type: string required: - name - description - grain - joinKeys - timeColumn - freshness - columns - exampleSql additionalProperties: false appFunctions: readOnly: true type: array items: type: object properties: name: type: string signature: type: string description: type: string returns: type: string encoding: type: string keyKind: type: string kind: type: string enum: - extraction - eval cap: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 gates: readOnly: true type: array items: anyOf: - type: string enum: - input - output - costs - type: string enum: - organization:view - organization:manage - organization:delete - project:view - project:create - project:update - project:delete - project:manage - team:view - team:manage - analytics:view - analytics:create - analytics:update - analytics:delete - analytics:manage - cost:view - traces:view - traces:create - traces:update - traces:share - scenarios:view - scenarios:create - scenarios:update - scenarios:delete - scenarios:manage - annotations:view - annotations:create - annotations:update - annotations:delete - annotations:manage - evaluations:view - evaluations:create - evaluations:update - evaluations:delete - evaluations:manage - datasets:view - datasets:create - datasets:update - datasets:delete - datasets:manage - triggers:view - triggers:create - triggers:update - triggers:delete - triggers:manage - workflows:view - workflows:create - workflows:update - workflows:delete - workflows:manage - experiments:view - experiments:create - experiments:update - experiments:delete - experiments:manage - prompts:view - prompts:create - prompts:update - prompts:delete - prompts:manage - secrets:view - secrets:create - secrets:update - secrets:delete - secrets:manage - playground:view - playground:create - playground:update - playground:delete - playground:manage - ops:view - ops:manage - auditLog:view - virtualKeys:view - virtualKeys:create - virtualKeys:update - virtualKeys:delete - virtualKeys:rotate - virtualKeys:manage - virtualKeys:viewOtherPersonal - gatewayBudgets:view - gatewayBudgets:create - gatewayBudgets:update - gatewayBudgets:delete - gatewayBudgets:manage - gatewayProviders:view - gatewayProviders:update - gatewayProviders:manage - routingPolicies:view - routingPolicies:manage - gatewayGuardrails:view - gatewayGuardrails:attach - gatewayGuardrails:detach - gatewayGuardrails:manage - gatewayLogs:view - gatewayUsage:view - gatewayCacheRules:view - gatewayCacheRules:create - gatewayCacheRules:update - gatewayCacheRules:delete - gatewayCacheRules:manage - governance:view - governance:manage - ingestionSources:view - ingestionSources:create - ingestionSources:update - ingestionSources:delete - ingestionSources:manage - anomalyRules:view - anomalyRules:create - anomalyRules:update - anomalyRules:delete - anomalyRules:manage - complianceExport:view - activityMonitor:view - aiTools:view - aiTools:manage - webhookEndpoints:view - webhookEndpoints:manage - gatewaySpend:view - gatewaySpend:manage - langy:view - langy:create - langy:update - langy:delete - langy:manage - agentCache:view - agentCache:manage - featureFlags:manageExperiments - governanceCost:view - sso:view - sso:manage available: type: boolean exampleSql: type: string required: - name - signature - description - returns - encoding - keyKind - kind - cap - gates - available - exampleSql additionalProperties: false required: - database - functions - views - appFunctions additionalProperties: false 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 additionalProperties: false endpoints: readOnly: true type: array items: type: object properties: method: type: string enum: - GET - POST path: type: string description: type: string required: - method - path - description additionalProperties: false required: - enabled - schema - limits - endpoints additionalProperties: false traceFilter: type: object properties: syntax: type: string fields: readOnly: true 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: readOnly: true type: array items: type: string required: - name - label - valueType - group - facetable - knownValues additionalProperties: false dynamicPrefixes: readOnly: true type: array items: type: object properties: prefix: type: string label: type: string description: type: string aliases: readOnly: true type: array items: type: string required: - prefix - label - description - aliases additionalProperties: false endpoints: readOnly: true type: array items: type: object properties: method: type: string enum: - GET - POST path: type: string description: type: string required: - method - path - description additionalProperties: false required: - syntax - fields - dynamicPrefixes - endpoints additionalProperties: false examples: readOnly: true 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: readOnly: true type: array items: type: string text: type: string parameters: readOnly: true type: array items: type: object properties: name: type: string type: type: string description: type: string required: - name - type - description additionalProperties: false requires: type: object properties: gates: readOnly: true type: array items: anyOf: - type: string enum: - input - output - costs - type: string enum: - organization:view - organization:manage - organization:delete - project:view - project:create - project:update - project:delete - project:manage - team:view - team:manage - analytics:view - analytics:create - analytics:update - analytics:delete - analytics:manage - cost:view - traces:view - traces:create - traces:update - traces:share - scenarios:view - scenarios:create - scenarios:update - scenarios:delete - scenarios:manage - annotations:view - annotations:create - annotations:update - annotations:delete - annotations:manage - evaluations:view - evaluations:create - evaluations:update - evaluations:delete - evaluations:manage - datasets:view - datasets:create - datasets:update - datasets:delete - datasets:manage - triggers:view - triggers:create - triggers:update - triggers:delete - triggers:manage - workflows:view - workflows:create - workflows:update - workflows:delete - workflows:manage - experiments:view - experiments:create - experiments:update - experiments:delete - experiments:manage - prompts:view - prompts:create - prompts:update - prompts:delete - prompts:manage - secrets:view - secrets:create - secrets:update - secrets:delete - secrets:manage - playground:view - playground:create - playground:update - playground:delete - playground:manage - ops:view - ops:manage - auditLog:view - virtualKeys:view - virtualKeys:create - virtualKeys:update - virtualKeys:delete - virtualKeys:rotate - virtualKeys:manage - virtualKeys:viewOtherPersonal - gatewayBudgets:view - gatewayBudgets:create - gatewayBudgets:update - gatewayBudgets:delete - gatewayBudgets:manage - gatewayProviders:view - gatewayProviders:update - gatewayProviders:manage - routingPolicies:view - routingPolicies:manage - gatewayGuardrails:view - gatewayGuardrails:attach - gatewayGuardrails:detach - gatewayGuardrails:manage - gatewayLogs:view - gatewayUsage:view - gatewayCacheRules:view - gatewayCacheRules:create - gatewayCacheRules:update - gatewayCacheRules:delete - gatewayCacheRules:manage - governance:view - governance:manage - ingestionSources:view - ingestionSources:create - ingestionSources:update - ingestionSources:delete - ingestionSources:manage - anomalyRules:view - anomalyRules:create - anomalyRules:update - anomalyRules:delete - anomalyRules:manage - complianceExport:view - activityMonitor:view - aiTools:view - aiTools:manage - webhookEndpoints:view - webhookEndpoints:manage - gatewaySpend:view - gatewaySpend:manage - langy:view - langy:create - langy:update - langy:delete - langy:manage - agentCache:view - agentCache:manage - featureFlags:manageExperiments - governanceCost:view - sso:view - sso:manage functions: readOnly: true type: array items: type: string required: - gates - functions additionalProperties: false available: type: boolean notes: type: string required: - id - title - intent - language - tags - text - parameters - requires - available additionalProperties: false decisionTable: readOnly: true type: array items: type: object properties: when: type: string use: type: string why: type: string required: - when - use - why additionalProperties: false required: - version - lwql - traceFilter - examples - decisionTable additionalProperties: false '400': description: Bad Request content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '500': description: Internal Server Error content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable 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.