VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dashboards

Preview, execução e detalhe

Testa um card sem salvar, executa todos os cards de uma aba de uma vez e abre as linhas por trás de um ponto de gráfico.

Estas três rotas são as que devolvem dados. Todas exigem apenas view_reports. O resultado de qualquer card, de qualquer tipo, tem o mesmo formato, o dataset: uma lista de colunas e uma lista de linhas, com a unidade de cada coluna explícita. A regra mais importante: a falha de um card nunca vira erro HTTP. A rota responde 200 e o problema vem em meta.error daquele card, para o painel desenhar um estado de erro em vez de quebrar a tela inteira.

Preview

POST/api/v1/admin/dashboards/previewAdmin

Executar uma especificação sem salvar

Corpo da requisição

specobjectobrigatório
A especificação do card a testar. Obrigatório.
periodobject

Período a aplicar aos cards com período inherit. Mesmo formato de period na especificação. Cards com período próprio ignoram este.

modestringobrigatório
inheritpresetfixedrelative
Como o período é definido.
presetstring
todayyesterdaylast7last30last90thisMonthlastMonththisQuarterthisYearlastYear
Obrigatório com mode=preset.
fromstring
Com mode=fixed: primeiro dia, YYYY-MM-DD.
tostring
Com mode=fixed: último dia, YYYY-MM-DD.
last_n_daysinteger
Com mode=relative: quantos dias para trás, até 1095.
fieldstring
Campo de data da entidade a usar como referência (entidade.campo). Padrão: o campo de data principal da entidade.
limitinteger
Reduz o limite de linhas (1 a 1000). Maiores que 1000 são ignorados.

Exemplo de requisição (preview)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"spec_version": 1, "kind": "query", "title": "Receita por dia", "viz": {"type": "line", "snippet_id": "receita-por-dia", "number_format": {"style": "currency_cents"}}, "query": {"entity": "orders", "period": {"mode": "preset", "preset": "last7"}, "metrics": [{"id": "receita", "kind": "catalog", "ref": "orders.revenue"}], "dimensions": [{"id": "dia", "field": "orders.created_at", "grain": "day", "fill_gaps": true}], "order": [{"by": "dia", "dir": "asc"}]}}}'

Resposta (preview)

200Resultado
json
{
  "dataset": {
    "columns": [
      { "key": "dia", "label": "dia", "type": "timestamp", "role": "dimension", "unit": "", "grain": "day" },
      { "key": "receita", "label": "receita", "type": "money_cents", "role": "metric", "unit": "cents" }
    ],
    "rows": [
      ["2026-10-09T00:00:00Z", "13587"],
      ["2026-10-10T00:00:00Z", "45000"]
    ],
    "meta": { "row_count": 2, "truncated": false, "limit": 100, "elapsed_ms": 2, "cached": false, "spec_hash": "0fac124f6f517da234ce129e4ef907afb4960daed43d8a48999548e42a89a6d9" }
  }
}

Campos da resposta

datasetobject
O resultado do card.
dataset.columnsarray
Colunas do resultado, na ordem das células de cada linha.
dataset.columns[].keystring
Chave da coluna (o id da métrica ou da dimensão na especificação).
dataset.columns[].labelstring
Rótulo. Em consultas comuns é igual a key.
dataset.columns[].typestring
Tipo de dado: money_cents, integer, percent_bps, timestamp, order_status, text e outros.
dataset.columns[].rolestring
dimensionmetric
dimension (eixo) ou metric (valor).
dataset.columns[].unitstring
cents (centavos), bps (pontos-base) ou vazio. Diz se a UI precisa dividir por 100.
dataset.columns[].grainstring
Granularidade de tempo, quando a coluna é uma data agrupada.
dataset.rowsarray
Linhas. Cada linha é uma lista de células (não um objeto), alinhada a columns. Números podem chegar como número JSON ou como texto numérico ("13587"): converta nos dois casos.
dataset.metaobject
Como o resultado foi produzido.
dataset.meta.row_countinteger
Linhas devolvidas.
dataset.meta.truncatedboolean
true se o limite cortou linhas.
dataset.meta.limitinteger
Limite aplicado.
dataset.meta.elapsed_msinteger
Tempo de execução em ms.
dataset.meta.cachedboolean
true se veio do cache.
dataset.meta.spec_hashstring
Identificador estável da especificação executada.
dataset.meta.warningsarray
Avisos não fatais (lista de códigos de texto).
dataset.meta.errorobject
Presente quando o card falhou: code (código estável) e message_key (chave de tradução). A falha de um card NÃO vira erro HTTP.
compiledobject
Diagnóstico da consulta gerada, só para quem tem manage_reports e só em cards query. Não faz parte do contrato estável: não dependa dele.

Erros (preview)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
403Especificação kind: sql sem o privilégio manage_reports.{"error":"manage_reports required for kind=\"sql\" cards"}
422Especificação inválida.{"error":"invalid spec","detail":"unknown_field: ..."}
500Falha inesperada no servidor.{"error":"failed to ..."}

Executar a aba

POST/api/v1/admin/dashboards/{id}/runAdmin

Executar todos os cards de uma aba

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Corpo da requisição

periodobject

Período a aplicar aos cards com período inherit. Mesmo formato de period na especificação. Cards com período próprio ignoram este.

modestringobrigatório
inheritpresetfixedrelative
Como o período é definido.
presetstring
todayyesterdaylast7last30last90thisMonthlastMonththisQuarterthisYearlastYear
Obrigatório com mode=preset.
fromstring
Com mode=fixed: primeiro dia, YYYY-MM-DD.
tostring
Com mode=fixed: último dia, YYYY-MM-DD.
last_n_daysinteger
Com mode=relative: quantos dias para trás, até 1095.
fieldstring
Campo de data da entidade a usar como referência (entidade.campo). Padrão: o campo de data principal da entidade.
card_idsarray
Só estes cards. Vazio ou omitido executa todos os ativos. Ids desconhecidos são ignorados em silêncio.
refreshbooleanpadrão: false
true ignora o cache de resultados.

Exemplo de requisição (run)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/56a570ca-f6a1-4483-ba89-55bcea0b5c4a/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"card_ids": ["f4368e4f-e696-4a57-9ca8-a026ba5ad694"], "period": {"mode": "preset", "preset": "last90"}, "refresh": false}'

Resposta (run)

200Resultados, um por card
json
{
  "results": [
    {
      "card_id": "f4368e4f-e696-4a57-9ca8-a026ba5ad694",
      "status": "ok",
      "dataset": {
        "columns": [
          { "key": "status", "label": "status", "type": "order_status", "role": "dimension", "unit": "" },
          { "key": "pedidos", "label": "pedidos", "type": "integer", "role": "metric", "unit": "" }
        ],
        "rows": [ ["C", 1630], ["S", 650], ["O", 145] ],
        "meta": { "row_count": 3, "truncated": false, "limit": 20, "elapsed_ms": 7, "cached": false, "spec_hash": "909130ef2a69eb9d303cbad672e6197dcafab6653d010c0223462d25a0dbd00a" }
      }
    },
    { "card_id": "4ffa2776-0000-4000-8000-000000000002", "status": "native" },
    { "card_id": "52ff7b72-0000-4000-8000-000000000003", "status": "error", "error": { "code": "invalid_stored_spec", "message_key": "admin.dashboards.err.invalid_stored_spec" } }
  ],
  "meta": { "elapsed_ms": 22, "concurrency": 4 }
}

Campos da resposta

resultsarray
Um item por card executado. A ordem não segue a da aba: use card_id.
results[].card_iduuid
Id do card.
results[].statusstring
okerrornative
ok (veja dataset), error (veja error) ou native (card de componente: não há dado, o painel o desenha sozinho).
results[].datasetobject
Resultado do card, no formato descrito em Preview. Só com status: ok.
results[].errorobject
code e message_key do problema. Só com status: error.
meta.elapsed_msinteger
Tempo total, em ms.
meta.concurrencyinteger
Cards executados em paralelo (fixo em 4).

Erros (run)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
404A aba não existe, não é sua ou não está visível para você. A API responde 404 em vez de 403 para não revelar que o id existe.{"error":"dashboard not found"}

Detalhe (drill-down)

POST/api/v1/admin/dashboards/cards/{cardId}/drilldownAdmin

Abrir as linhas por trás de um ponto de gráfico

Parâmetros de caminho

cardIduuidobrigatório
Id do card (UUID).

Corpo da requisição

dimension_valuesobjectobrigatório
Mapa do id de cada dimensão do card para o valor clicado ({ "status": "O" }). Dimensões de data aceitam o início do período (RFC 3339 ou YYYY-MM-DD), que vira um intervalo conforme a granularidade. Dimensões não citadas não filtram.
periodobject

Período a aplicar aos cards com período inherit. Mesmo formato de period na especificação. Cards com período próprio ignoram este.

modestringobrigatório
inheritpresetfixedrelative
Como o período é definido.
presetstring
todayyesterdaylast7last30last90thisMonthlastMonththisQuarterthisYearlastYear
Obrigatório com mode=preset.
fromstring
Com mode=fixed: primeiro dia, YYYY-MM-DD.
tostring
Com mode=fixed: último dia, YYYY-MM-DD.
last_n_daysinteger
Com mode=relative: quantos dias para trás, até 1095.
fieldstring
Campo de data da entidade a usar como referência (entidade.campo). Padrão: o campo de data principal da entidade.
pageintegerpadrão: 1
Página, a partir de 1. Máximo 200.
per_pageintegerpadrão: 25
Linhas por página, 1 a 1000. Fora disso vale 25.
langstring
Idioma dos rótulos das colunas (pt-BR ou en). Sem isso, usa Accept-Language e depois pt-BR.

Exemplo de requisição (drilldown)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/cards/f4368e4f-e696-4a57-9ca8-a026ba5ad694/drilldown" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dimension_values": {"status": "O"}, "per_page": 2, "lang": "en"}'

Resposta (drilldown)

200Linhas do detalhe
json
{
  "dataset": {
    "columns": [
      { "key": "dd_status", "label": "Status", "type": "order_status", "role": "dimension", "unit": "" },
      { "key": "dd_created_at", "label": "Created at", "type": "timestamp", "role": "dimension", "unit": "" },
      { "key": "dd_total", "label": "Total", "type": "money_cents", "role": "dimension", "unit": "cents" },
      { "key": "dd_order_number", "label": "Order", "type": "text", "role": "dimension", "unit": "" }
    ],
    "rows": [
      ["O", "2026-10-10T07:03:38Z", 22500, "PEDIDO-20261010-0003"],
      ["O", "2026-10-09T08:51:21Z", 13587, "PEDIDO-20261009-0002"]
    ],
    "meta": { "row_count": 2, "truncated": false, "limit": 2, "elapsed_ms": 1, "cached": false }
  },
  "entity": "orders",
  "page": 1,
  "per_page": 2,
  "has_more": true,
  "filters": { "orders.status": "O" },
  "period_from": "2026-09-12",
  "period_to": "2026-10-11"
}

Campos da resposta

datasetobject
As linhas cruas (sem agregação), mais recentes primeiro quando a entidade tem data. Mesmo formato do dataset; as colunas têm prefixo dd_.
entitystring
Entidade consultada.
pageinteger
Página devolvida.
per_pageinteger
Linhas por página usadas.
has_moreboolean
true se há uma próxima página.
filtersobject
Filtros aplicados, pelo nome do campo (orders.status), não pelo id da dimensão.
period_fromstring
Início do período efetivo, YYYY-MM-DD.
period_tostring
Fim do período efetivo.

Erros (drilldown)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
404O card não existe ou a aba dele não é sua.{"error":"card not found"}
400O card não é do tipo query.{"error":"drilldown_requires_query_card"}
422Entidade fora do catálogo, sem colunas projetáveis, ou falha ao montar o detalhe.{"error":"drilldown_no_columns"}
500Falha inesperada no servidor.{"error":"failed to ..."}
Confira meta.error antes de ler as linhas

Mesmo com HTTP 200, um card pode ter falhado (código em meta.error.code, ou status: error em /run). O /run resolve o período de cada card sozinho: cards com período inherit usam o seu period ou, na falta, o período padrão da aba; cards com período próprio ignoram os dois.

Números como texto

Nas células do dataset, valores inteiros grandes (dinheiro em centavos, por exemplo) podem chegar como texto ("13587") em vez de número. Use columns[].unit: cents pede divisão por 100, bps por 100 para virar porcentagem.

Cartões de texto

Cards kind: text não consultam nada e não aparecem em results.

Veja também

  • Especificação do card
  • Consultar uma aba
  • Insights e narrativa
Anterior
Cards: ações
Próxima
Gerar card por texto (IA)
Nesta página
  • Preview
  • Exemplo de requisição (preview)
  • Resposta (preview)
  • Erros (preview)
  • Executar a aba
  • Exemplo de requisição (run)
  • Resposta (run)
  • Erros (run)
  • Detalhe (drill-down)
  • Exemplo de requisição (drilldown)
  • Resposta (drilldown)
  • Erros (drilldown)
  • Veja também