---
title: "Run SQL against one durable storage bucket."
method: POST
path: "/v1/storage/{storage_id}/query"
tags: ["storage"]
---

# Run SQL against one durable storage bucket.

`POST /v1/storage/{storage_id}/query`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/storage/{storage_id}/query`
- Auth: HTTP bearer

Run SQL against one durable storage bucket. Requires package:write (connection-profile write) whenever storage_id resolves to a package bucket — including writable:false SELECT/EXPLAIN/PRAGMA inspection. Defaults to read-only SQL and only allows SELECT, EXPLAIN, and schema PRAGMA queries unless writable is explicitly true. A large read is allowed and metered; warning is set once the scan crosses the oversized-read line, and the call stops only after the documented row ceiling.

Org permission: `package:write`.

## Path parameters

- `storage_id` string, required: Durable storage id to inspect.

## Request body

- object
  - `query` string, required
  - `params` union[]: Optional positional SQL bindings.
    - union
      - string
      - number
      - boolean
  - `writable` boolean: Optional write access toggle. Defaults to false for inspection workflows.

## Response `200`

Success.

- object
  - `ok` true, required
  - `storage_id` string, required
  - `query` string, required
  - `columns` string[], required
  - `rows` object[], required
  - `row_count` number, required
  - `rows_read` number, required
  - `rows_written` number, required
  - `truncated` boolean, required
  - `warning` string, nullable, required: Set when this statement examined at least 1000000 rows. The read is allowed and metered on the monthly Rows read include. Null under that line. A read stops after 1000000000 rows.
  - `writable` boolean, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/705f4f022728?raw)