> ## Documentation Index > Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Run Sql > 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. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/public/sql openapi: 3.1.0 info: title: TraceRoot Public API version: 0.1.0 servers: - description: TraceRoot Cloud url: https://app.traceroot.ai - description: Self-hosted url: '{baseUrl}' variables: baseUrl: default: http://localhost:8000 description: Your TraceRoot backend URL security: [] paths: /api/v1/public/sql: post: tags: - SQL summary: Run Sql description: |- 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. operationId: run_sql parameters: - description: >- 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. in: query name: project_id required: false schema: anyOf: - type: string - type: 'null' description: >- 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. title: Project Id requestBody: content: application/json: schema: $ref: '#/components/schemas/SqlRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SqlResponse' description: Successful Response '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The query breaks the read-only contract, asked for more than the server allows, or the credential names no project '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication failed '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The credential cannot access this project '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Request body too large '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit exceeded, or too many queries are already running '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Query execution failed '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication service unavailable security: - BearerAuth: [] components: schemas: SqlRequest: additionalProperties: false description: >- 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. properties: max_rows: anyOf: - maximum: 1000000 minimum: 1 type: integer - type: 'null' description: Rows to return, clamped down to the server ceiling title: Max Rows parameters: anyOf: - additionalProperties: true maxProperties: 100 type: object - type: 'null' description: Values for {name:Type} placeholders in the query title: Parameters query: description: A single read-only SELECT over the public schema maxLength: 65536 minLength: 1 title: Query type: string required: - query title: SqlRequest type: object SqlResponse: description: A completed query, already trimmed to what the caller may receive. properties: columns: items: $ref: '#/components/schemas/SqlColumn' title: Columns type: array elapsed_ms: title: Elapsed Ms type: integer row_count: title: Row Count type: integer rows: items: items: {} type: array title: Rows type: array statistics: additionalProperties: true title: Statistics type: object truncated: description: True when more rows matched than were returned title: Truncated type: boolean required: - columns - rows - row_count - truncated - elapsed_ms title: SqlResponse type: object ErrorResponse: description: >- The canonical public error envelope (matches the gateway's normalized shape). properties: detail: title: Detail type: string required: - detail title: ErrorResponse type: object SqlColumn: description: One column of a result, named and typed as ClickHouse reported it. properties: name: title: Name type: string type: title: Type type: string required: - name - type title: SqlColumn type: object securitySchemes: BearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.