---
title: "Run Sql"
method: POST
path: "/api/v1/public/sql"
tags: ["SQL"]
---

# Run Sql

`POST /api/v1/public/sql`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/sql`
- Auth: HTTP bearer

Run one read-only SQL query scoped to the caller's project.

Args:
    auth (DualStampedAuth): Resolved credential context. Its ``project_id``
        is the only project this query can ever see.
    body (SqlRequest): The query, optional parameter values, and an optional
        row cap that the service clamps down to the server ceiling.

Returns:
    SqlResponse: Columns, rows, and whether more rows matched than were
        returned.

Raises:
    HTTPException: 400 when the query breaks the read-only contract or asks
        for more than the server allows, 429 when no query slot is free,
        500 when execution fails for a reason the caller cannot act on.

## Query parameters

- `project_id` string, nullable: Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.

## Request body

- SqlRequest: A public SQL query. The project is never part of this body. ``extra="forbid"`` is the point rather than tidiness: scope is resolved from the credential, so a body carrying ``project_id`` or a ``scope_*`` key is a caller trying to choose a tenant. Forbidding unknown keys turns that into a 422 instead of a silently ignored field.
  - `max_rows` integer, nullable: Rows to return, clamped down to the server ceiling
  - `parameters` object, nullable: Values for {name:Type} placeholders in the query
  - `query` string, required: A single read-only SELECT over the public schema

## Response `200`

Successful Response

- SqlResponse: A completed query, already trimmed to what the caller may receive.
  - `columns` SqlColumn[], required
    - `name` string, required
    - `type` string, required
  - `elapsed_ms` integer, required
  - `row_count` integer, required
  - `rows` array[], required
    - unknown[]
      - unknown
  - `statistics` object
  - `truncated` boolean, required: True when more rows matched than were returned

## Other responses

- `400`: The query breaks the read-only contract, asked for more than the server allows, or the credential names no project
- `401`: Authentication failed
- `403`: The credential cannot access this project
- `413`: Request body too large
- `422`: Validation error
- `429`: Rate limit exceeded, or too many queries are already running
- `500`: Query execution failed
- `503`: Authentication service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)