Run database query
POSThttps://api.instacloud.com/projects/{projectId}/database/query
Token scope: account · org · project — read-only tokens refused (not a GET).
Run one SQL statement with the service credential (full privileges — the gate and audit are a record, not a permission boundary). The audit log records a statement hash and parameter count, never SQL text or values. Gated — db.query. May wake a suspended database.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
branch | query | string | no | Branch name (defaults to the project's default branch) |
group | query | string | no | postgres service name (default: the sole postgres service) |
database | query | string | no | database on the instance (default: the connection-string database) |
projectId | path | string | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
sql | string | yes | |
params | any[] | no | positional parameter values for $1..$n — audited as a count, never as values |
maxRows | integer | no |
Responses
200
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
columns | object[] | yes | |
columns.name | string | yes | |
columns.dataTypeID | integer | yes | |
rows | any[][] | yes | rows as positional cells — duplicate column names stay distinct; numeric/int8 arrive as strings |
rowCount | integer | yes | |
truncated | boolean | yes | true when maxRows clipped the result — narrow with WHERE/LIMIT |
queryId | null | null | yes | reserved for future cancellation |
202
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
status | "approval_required" | no | |
approvalId | string | no | |
action | string | no | the gated action, or a comma-joined compound set — prefer `actions` |
actions | string[] | no | every capability this approval covers |
message | string | no | |
url | string | no | the console page where a project admin reviews this request |
nextActions | object[] | no | |
nextActions.op | string | yes | Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface. |
nextActions.reason | string | yes | Natural-language, human/LLM-facing "why do this now". |
nextActions.args | object | no | Suggested, flat named arguments; "<placeholder>"s where a value is unknown. |
nextActions.gated | boolean | no | True if the action passes a governance gate. |
400
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
403
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
404
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
409
code public_access_closed: the database's public access is closed and the console has no private lane on this deployment yet
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | |
code | string | no | stable machine-readable reason, e.g. private_lane_disabled, private_lane_unavailable_in_region, public_access_closed, credential_change_in_progress |
502
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |