> ## 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. # Run a LangWatchQL query > Executes one read-only LangWatchQL SELECT over the analytics datasets and returns typed columns, rows, execution statistics, truncation state and diagnostics. The query runs as a restricted database identity scoped to the authenticated project. Diagnostics are advisory and never reject a query. An empty diagnostics list means no known issue was detected. It is not proof that the answer is the one you meant. The project is taken from the credential — no project id appears anywhere in the path or the body, and none can be sent to select another one. Failures answer with their real HTTP status (a refused query is 403, not 200) and this API's canonical error envelope — the same `code` and `meta` every other REST family publishes. ## OpenAPI ````yaml POST /api/v1/query 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: post: tags: - Query summary: Run a LangWatchQL query description: >- Executes one read-only LangWatchQL SELECT over the analytics datasets and returns typed columns, rows, execution statistics, truncation state and diagnostics. The query runs as a restricted database identity scoped to the authenticated project. Diagnostics are advisory and never reject a query. An empty diagnostics list means no known issue was detected. It is not proof that the answer is the one you meant. The project is taken from the credential — no project id appears anywhere in the path or the body, and none can be sent to select another one. Failures answer with their real HTTP status (a refused query is 403, not 200) and this API's canonical error envelope — the same `code` and `meta` every other REST family publishes. operationId: postApiV1Query requestBody: required: true content: application/json: schema: type: object properties: sql: type: string minLength: 1 maxLength: 50000 parameters: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' timeWindow: type: object properties: start: anyOf: - type: string - type: number - type: string description: >- A value already parsed into a native Date. A JSON request body cannot produce this shape — send a string or a number instead. end: anyOf: - type: string - type: number - type: string description: >- A value already parsed into a native Date. A JSON request body cannot produce this shape — send a string or a number instead. required: - start - end granularitySeconds: anyOf: - type: number const: 1 - type: number const: 60 - type: number const: 3600 required: - sql responses: '200': description: >- The query ran. Columns, rows, execution statistics, truncation state and diagnostics, scoped to the caller's project. content: application/json: schema: type: object properties: columns: type: array items: type: object properties: name: type: string type: type: string required: - name - type rows: type: array items: type: object additionalProperties: {} statistics: type: object properties: elapsedMs: type: number rowsRead: type: number bytesRead: type: number rowsReturned: type: number required: - elapsedMs - rowsRead - bytesRead - rowsReturned truncated: type: boolean followsTimeWindow: type: boolean followsGranularity: type: boolean granularitySeconds: type: number coarsenedFromSeconds: type: number diagnostics: type: array items: type: object properties: code: type: string enum: - RESULT_TRUNCATED - POSSIBLE_FANOUT - UNBOUNDED_TIME_RANGE - MISSING_TIME_BUCKETS - INCOMPLETE_COMPARISON_PERIOD message: type: string meta: type: object additionalProperties: {} required: - code - message required: - columns - rows - statistics - truncated - followsTimeWindow - followsGranularity - diagnostics '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 '422': description: Unprocessable Entity 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. ````