Endpoint: POST /api/v1/query — ingestia.io Documentation

This page has not been translated yet — you are reading the Portuguese version. View in Portuguese

Selo de estado: Preview (badge) — na prática, FORA DE GA: SQL livre via API está indisponível para uso externo hoje (dispara processamento cobrável no datalake; rate-limit fail-closed em endurecimento). Atualizado em 2026-09-08.

Fora de GA hoje

Contrato documentado para planejamento. Não construa integrações críticas sobre SQL livre via API enquanto não for liberado. Para leitura externa hoje, use o feed OData.

Executa SQL somente leitura (SELECT/WITH … SELECT) escopado ao workspace, sobre os marts publicados. Não há API de escrita.

Resumo#


Método · rota	`POST /api/v1/query`
Base	`https://ingestia.io`
Auth	Chave de API + escopo `read`/`read_query`
Papel (RBAC)	`data.query.run` (admin+); chave de dados = owner
Corpo	`{ "sql": string, "limit"?: number }`
Custo	bytes reais processados no datalake; cache de query idêntica = R$ 0
Estados	`200` · `400` · `401` · `403` · `429` · `402` · `502` · `503`

Defesas aplicadas (em camadas, antes de tocar o datalake)#

Só SELECT — qualquer INSERT/UPDATE/DELETE/MERGE/DDL/… → 403.
Sem cruzar workspace — dataset de outro cliente ou outro projeto → 403.
Sem construções perigosas — EXTERNAL_QUERY, INFORMATION_SCHEMA, JOBS_*, etc. → 403.
Só marts publicados — apenas *_gold/*_silver; referência a bronze ou outro dataset → 403.
Guarda de custo — teto de bytes faturados no job.

Exemplo#

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 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 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 aurora_gold.vendas GROUP BY data",
        "limit": 500,
    },
)
dados = res.json

Resposta `200`#

json

{ "rows": [ { "data": "2026-09-01", "total": 1234.56 } ], "rowCount": 42 }

Se o resultado for cortado por segurança, a resposta inclui "truncated": true e "totalRows" — para a soma do outro lado não sair errada. Cabeçalhos: x-ingestia-cost-brl (custo projetado) e x-ingestia-cache (hit/miss).

Cache#

Consultas idênticas (mesma versão do workspace) servem do cache com custo R$ 0 (x-ingestia-cache: hit). A invalidação por pipeline/DML garante que nunca se serve dado velho.

Erros#

Código	Mensagem típica
`400`	corpo inválido / `sql` ausente
`401`	chave ausente/inválida
`403`	`Apenas consultas SELECT…` · fora do workspace · só marts publicados · escopo `read_query` ausente
`429` · `402`	rate limit (60/min por chave) / inadimplência
`502`	falha ao executar no datalake
`503`	datalake não provisionado / limitador indisponível

Segurança#

Somente leitura + escopo por workspace (marts publicados apenas).
Colunas PII não são expostas.
Consulta e custo ficam registrados na auditoria.

Relacionados#

Última revisão: 2026-09-08. Estado: SQL livre via API fora de GA (badge Preview). Fonte: matriz de estados do produto.