The REST query API (
/api/v1) is in early access and not yet open for external use. The code exists and the contract below reflects the current behavior. Free-form SQL through the API triggers billable processing in the datalake. For external consumption now, use the OData feed.
Early access
Contract documented for planning. Do not build critical integrations on free-form SQL via the API until it is released. For external reads today, use the OData feed.
Runs read-only SQL (SELECT/WITH … SELECT) scoped to the workspace,
over the published marts. There is no write API.
Summary#
| Method · route | POST /api/v1/query |
| Base | https://ingestia.io |
| Auth | API key + read/read_query scope |
| Role (RBAC) | data.query.run (admin+); data key = owner |
| Body | { "sql": string, "limit"?: number } |
| Cost | actual bytes processed in the datalake; cached identical query = R$ 0 |
| Statuses | 200 · 400 · 401 · 403 · 429 · 402 · 502 · 503 |
Defenses applied (in layers, before touching the datalake)#
SELECTonly — anyINSERT/UPDATE/DELETE/MERGE/DDL/…→403.- No crossing workspaces — another customer's dataset or another project →
403. - No dangerous constructs —
EXTERNAL_QUERY,INFORMATION_SCHEMA,JOBS_*, etc. →403. - Published marts only — only
*_gold/*_silver; a reference tobronzeor any other dataset →403. - Cost guard — cap on bytes billed per job.
Example#
curl -X POST https://ingestia.io/api/v1/query \
-H "Authorization: Bearer ing_live_EXEMPLO" \
-H "Content-Type: application/json" \
-d '{"sql":"SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data","limit":500}'const res = await fetch("https://ingestia.io/api/v1/query", {
method: "POST",
headers: {
Authorization: "Bearer ing_live_EXEMPLO",
"Content-Type": "application/json",
},
body: JSON.stringify({
sql: "SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data",
limit: 500,
}),
});
const dados = await res.json();import requests
res = requests.post(
"https://ingestia.io/api/v1/query",
headers={
"Authorization": "Bearer ing_live_EXEMPLO",
"Content-Type": "application/json",
},
json={
"sql": "SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data",
"limit": 500,
},
)
dados = res.json()200 response#
{ "rows": [ { "data": "2026-09-01", "total": 1234.56 } ], "rowCount": 42 }If the result is cut off for safety, the response includes "truncated": true and
"totalRows" — so the sum on the other end does not come out wrong. Headers:
x-ingestia-cost-brl (projected cost) and x-ingestia-cache (hit/miss).
Cache#
Identical queries (same workspace version) are served from the cache at a cost
of R$ 0 (x-ingestia-cache: hit). Invalidation by pipeline/DML ensures stale
data is never served.
Errors#
| Code | Typical message |
|---|---|
400 | invalid body / missing sql |
401 | missing/invalid key |
403 | Apenas consultas SELECT… · outside the workspace · published marts only · missing read_query scope |
429 · 402 | rate limit (60/min per key) / overdue payment |
502 | failed to run in the datalake |
503 | datalake not provisioned / limiter unavailable |
Security#
- Read-only + workspace scope (published marts only).
- PII columns are not exposed.
- The query and its cost are recorded in the audit log.
Related#
Last reviewed: 2026-09-08.