Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-09-08

Endpoint: POST /api/v1/query

Reference for the read-only free-form SQL endpoint (SELECT) scoped to the workspace, with layered defenses and a cost guard.

On this page (8)

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 · routePOST /api/v1/query
Basehttps://ingestia.io
AuthAPI key + read/read_query scope
Role (RBAC)data.query.run (admin+); data key = owner
Body{ "sql": string, "limit"?: number }
Costactual bytes processed in the datalake; cached identical query = R$ 0
Statuses200 · 400 · 401 · 403 · 429 · 402 · 502 · 503

Defenses applied (in layers, before touching the datalake)#

  1. SELECT only — any INSERT/UPDATE/DELETE/MERGE/DDL/… → 403.
  2. No crossing workspaces — another customer's dataset or another project → 403.
  3. No dangerous constructs — EXTERNAL_QUERY, INFORMATION_SCHEMA, JOBS_*, etc. → 403.
  4. Published marts only — only *_gold/*_silver; a reference to bronze or any other dataset → 403.
  5. 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}'

200 response#

json
{ "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#

CodeTypical message
400invalid body / missing sql
401missing/invalid key
403Apenas consultas SELECT… · outside the workspace · published marts only · missing read_query scope
429 · 402rate limit (60/min per key) / overdue payment
502failed to run in the datalake
503datalake 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.

Related links