> ## 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.

# Overview

> Run a read-only LangWatchQL SELECT over your project's analytics datasets, or discover which datasets and columns your key can query.

## Intro

The Query API runs read-only LangWatchQL `SELECT` statements over your project's analytics datasets. `POST /api/v1/query` runs one statement. `GET /api/v1/query/schema` lists the datasets and columns your key can query.

## Endpoints

| Method | Path                   | Description                                             |
| ------ | ---------------------- | ------------------------------------------------------- |
| `POST` | `/api/v1/query`        | Run one LangWatchQL statement.                          |
| `GET`  | `/api/v1/query/schema` | List queryable datasets, columns, and permission gates. |

## Authentication

Pass your LangWatch API key in the `X-Auth-Token` header.

## Errors

Both endpoints answer with the standard LangWatch error envelope and a real HTTP status. No wrapper sits around it. See [Error Envelope](/docs/ai-gateway/api/errors).

| Status | `type`                 | When                                                                 |
| ------ | ---------------------- | -------------------------------------------------------------------- |
| `400`  | `bad_request`          | The request body failed validation.                                  |
| `401`  | `unauthenticated`      | The API key is missing, invalid, or revoked.                         |
| `403`  | `permission_denied`    | The key lacks the `analytics:view` permission.                       |
| `422`  | `unprocessable_entity` | The statement is valid but would scan more data than the key allows. |