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)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({sql: '<string>'})
};
fetch('https://app.langwatch.ai/api/v1/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://app.langwatch.ai/api/v1/query \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"sql": "<string>"
}
'{
"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>"
]
}
}
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}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.
Any LangWatch API key — project, organization or personal — reaches every project it can read analytics:view on: an organization or personal key spans its projects, a project key its one. Rows from more than one project come back flagged with the MULTI_PROJECT_RESULT diagnostic — to read a single project, filter inside the statement with WHERE TenantId = '<project id>'.
To run over one project only, send its id as projectId in the body: the run then reads that project’s rows alone, redacted by that project’s own protections. A projectId the key cannot read analytics:view on, in its own organization, is refused with project_not_found (404), the same answer as a project that does not exist. Without projectId the run spans every project the key can read.
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.
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)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({sql: '<string>'})
};
fetch('https://app.langwatch.ai/api/v1/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://app.langwatch.ai/api/v1/query \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"sql": "<string>"
}
'{
"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>"
]
}
}
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"meta": {},
"trace_id": "<string>",
"span_id": "<string>",
"trace": {
"traceId": "<string>",
"spanId": "<string>",
"traceUrl": "<string>",
"logsUrl": "<string>"
},
"tips": [
"<string>"
],
"docs_url": "<string>",
"fault": "customer",
"reasons": [
"<unknown>"
]
}Authorizations
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
1 - 50000Show child attributes
Show child attributes
Show child attributes
Show child attributes
Narrows the run to this one project, which the key must hold analytics:view on. Without it the run spans every project the key can read.
1Response
The query ran. Columns, rows, execution statistics and diagnostics, scoped to the projects the key can read, or to the one project projectId names.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Was this page helpful?