Run a LangWatchQL query

Executes one read-only LangWatchQL SELECT over the analytics views and returns typed columns, rows, execution statistics and diagnostics. The query runs as a restricted database identity scoped to the projects this key can read.

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.

A projection may call the app functions the schema endpoint lists (conversation, llm_readable_trace, llm_messages, and so on). Those are computed by the application after the query, so they are allowed only as aliased entries in the top-level SELECT list; a call in WHERE, GROUP BY, ORDER BY, a join, a subquery or a nested expression is refused, and a UNION disqualifies both of its branches even where each reads as a top-level projection. A projection may also call the eval functions, which judge a text with a model and are charged for; their key is the text itself. A run that would need more distinct conversations, traces, spans or texts than the published cap answers 422 rather than a partial result, and a run whose texts would exceed the per-query token budget answers 422 before anything is sent.

A project API key, or any key that can read exactly one project, reads that project and needs none. A key that reaches several must name the projects to read in projects, each one it can read analytics:view on; without them the run is refused with projects_required (422). A key that reads no project is refused with projects_unreadable (422) when it names no project or sends “all”; a project it names and cannot read is project_not_found (404). Rows from more than one project come back flagged with the MULTI_PROJECT_RESULT diagnostic.

Send projects, a list of project ids, to name the projects to read; projectId (one id) still works, and sending both is a 422. A project the key cannot read analytics:view on, a project of another organization and a project that does not exist are all refused with project_not_found (404), with one body that names no id. Send sources to bind {dashboard_context_sources:Array(String)} (application when absent); only a statement that reads that placeholder is kept to those origins. {dashboard_context_projects:Array(String)} is bound to the projects read. The answer’s params lists every placeholder the statement declares by its SQL name with the value it ran with, plus the period it followed. A SOURCES_IGNORED diagnostic says sources changed nothing; GRANULARITY_COARSENED says the step ran coarser than asked.

A statement that names no LIMIT is capped at 10,000 rows: that LIMIT is appended before the query runs. A statement whose own LIMIT asks for more is refused with LIMIT_TOO_HIGH — lower it and page the rest with LIMIT/OFFSET and an ORDER BY. When using UNION, every top-level branch must carry its own LIMIT clause of 10,000 rows or fewer, or the query is refused with LIMIT_REQUIRED_PER_BRANCH. A result whose body exceeds about 8,000,000 bytes is refused outright with lwql_result_too_large, never cut — select fewer columns or a smaller LIMIT.

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.

POST /api/v1/query

Run a LangWatchQL query

Python

import requests

url = "https://app.langwatch.ai/api/v1/query"

payload = { "sql": "<string>" }
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

200

{
  "columns": [
    {
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "rows": [
    {}
  ],
  "statistics": {
    "elapsedMs": 123,
    "rowsRead": 123,
    "bytesRead": 123,
    "rowsReturned": 123
  },
  "diagnostics": [
    {
      "code": "MULTI_PROJECT_RESULT",
      "message": "<string>",
      "meta": {}
    }
  ],
  "followsTimeWindow": true,
  "followsGranularity": true,
  "granularitySeconds": 123,
  "coarsenedFromSeconds": 123,
  "completeness": {
    "state": "complete",
    "unit": "<string>",
    "total": 123,
    "fields": [
      {
        "field": "<string>",
        "label": "<string>",
        "present": 123
      }
    ],
    "buckets": [
      {
        "start": "<string>",
        "n": 123
      }
    ],
    "unpriced": {
      "count": 123,
      "models": [
        "<string>"
      ]
    }
  },
  "params": {}
}

Authorizations

X-Auth-Token · string · header · required

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.

Body

application/json

sql · string · required

Required string length: 1 - 50000

parameters · object

Show child attributes

timeWindow · object

Show child attributes

granularitySeconds · Option 1 · number Option 2 · number Option 3 · number Option 4 · number Option 5 · number

projectId · string

Reads this one project, which the key must hold analytics:view on. Send projectId or projects, not both.

Minimum string length: 1

projects · string string[]

The projects to read, each one the key holds analytics:view on, or the string "all" for every project the key can read. A key that reaches several projects must name them or send "all"; a key that reads one project defaults to it. When the statement declares {dashboard_context_projects:Array(String)}, params.dashboard_context_projects lists what was read.

Pattern: ^\s*[aA][lL][lL]\s*$

sources · enum<string>[]

The trace origins {dashboard_context_sources:Array(String)} is bound to; application when absent. The placeholder does not filter by itself: the statement keeps its rows with a predicate such as WHERE Source IN {dashboard_context_sources:Array(String)}. A statement that never uses the placeholder counts every origin.

Maximum array length: 11

Available options: application, simulation, evaluation, sample, coding_agent, ai_tool, gateway, workflow, playground, langy, other

Response

200

application/json

The query ran. Columns, rows, execution statistics and diagnostics, scoped to the projects the key can read, or to the one project projectId names.

columns · object[] · required · read-only

Show child attributes

rows · object[] · required · read-only

Show child attributes

statistics · object · required

Show child attributes

diagnostics · object[] · required · read-only

Show child attributes

followsTimeWindow · boolean · required

followsGranularity · boolean · required

granularitySeconds · number

coarsenedFromSeconds · number

completeness · object

Show child attributes

params · object

Show child attributes