Skip to main content
POST
/
v3
/
query
curl --request POST \
  --url https://api.metrito.com/v3/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "69162064162b926ae607959b",
  "fields": [
    "spend",
    "impressions",
    "clicks"
  ],
  "time": {
    "start": "2026-02-01",
    "end": "2026-02-08"
  }
}
'
{
  "success": true,
  "data": [
    {
      "spend": 1250.75,
      "impressions": 45230,
      "clicks": 1205,
      "ctr": 0.0266,
      "cpc": 1.038
    }
  ],
  "currency": "BRL"
}

​
Autenticação

Este endpoint aceita dois formatos de autenticação:
  1. JWT da plataforma
    • Header: Authorization: Bearer {jwt}
    • Header adicional obrigatório: X-Workspace-Id
  2. API Key do Metrito
    • Header: Authorization: Bearer mtk_live_... ou x-api-key: mtk_live_...
    • Não precisa enviar X-Workspace-Id (o workspace é resolvido pela própria chave)

​
Métricas Disponíveis

​
Métricas Base (sincronizadas das APIs)

MétricaDescrição
spendValor gasto em anúncios
impressionsVezes que o anúncio foi exibido
clicksCliques no anúncio
reachPessoas únicas alcançadas (apenas Meta)
video_playsVezes que o vídeo começou a rodar
video_views_p75Visualizações até 75% do vídeo

​
Métricas Calculadas — Eficiência de Tráfego

MétricaFórmulaDescrição
ctrclicks / impressionsTaxa de clique
cpcspend / clicksCusto por clique
cpm(spend / impressions) * 1000Custo por mil impressões
frequencyimpressions / reachFrequência média

​
Métricas Calculadas — Análise de Vídeo

MétricaFórmulaDescrição
hook_ratevideo_views_3s / impressionsQualidade do hook (3s)
hold_ratevideo_views_p75 / impressionsQualidade do conteúdo (75%)
play_ratevideo_plays / impressionsTaxa de play
cta_rateclicks / video_views_p75Eficácia do CTA

​
Métricas Calculadas — Atribuição de Vendas

MétricaDescrição
tx_revenueFaturamento atribuído
tx_countVendas aprovadas
tx_count_totalVendas totais (inclui pendentes)
tx_count_pendingVendas pendentes
tx_count_refundedReembolsos
page_viewsVisualizações de página
leadsCadastros/leads
initiate_checkoutInícios de checkout

​
Métricas Calculadas — Financeiro

MétricaFórmulaDescrição
roastx_revenue / spendRetorno sobre investimento em ads
roi(tx_revenue - spend) / spendROI percentual
profittx_revenue - spend - tx_product_costsLucro líquido
aovtx_revenue / tx_countTicket médio
cpaspend / tx_countCusto por aquisição
cplspend / leadsCusto por lead

​
Granularidades

ValorDescrição
5min, 10min, 15min, 30minSub-horária (planos Growth/Enterprise)
hourHorária
dayDiária
weekSemanal
monthMensal
quarterTrimestral
yearAnual
Se a granularidade solicitada não tiver dados disponíveis, o sistema faz fallback automático para granularidades mais grossas (raw → hourly → daily).

​
Conversão de Moeda

A API converte automaticamente valores monetários para a moeda padrão do projeto. Para forçar uma moeda específica, use metadata.convert_to_currency. Apenas campos monetários são convertidos (spend, cpc, cpm, cpa, roas, profit, aov, etc.). Campos como clicks, impressions, ctr não são afetados.

Authorizations

​
Authorization
string
header
required

JWT da plataforma ou API key mtk_live_... enviada no header Authorization

Headers

​
X-Workspace-Id
string

Obrigatório quando usar JWT. Opcional quando usar API key (mtk_live_...)

Example:

"69162064162b926ae607959b"

Body

application/json
​
project_id
string
required

ID do projeto (brand) no Metrito

Example:

"69162064162b926ae607959b"

​
fields
string[]
required

Lista de métricas a consultar. Consulte GET /v3/fields para ver todas as opções.

Minimum array length: 1
Example:
["spend", "impressions", "clicks", "ctr"]
​
source
enum<string>

Plataforma de anúncios. Omita para consultar todas.

Available options:
meta_ads,
google_ads,
tiktok_ads
Example:

"meta_ads"

​
connection_ids
string[]

IDs de conexões específicas. Omita para usar todas as conexões do projeto.

​
time
object
​
filters
object[]

Filtros para restringir os dados retornados

​
order
object

Ordenação dos resultados. Ex: { "spend": "desc" }

Example:
{ "spend": "desc" }
​
limit
integer

Limite de resultados

Required range: 1 <= x <= 50000
Example:

100

​
offset
integer

Offset para paginação

Required range: x >= 0
​
metadata
object

Opções adicionais da query

Response

Dados retornados com sucesso

​
success
boolean
​
data
object[]

Resultados da query. Cada item contém as métricas solicitadas.

​
currency
string

Moeda dos valores monetários na resposta

Example:

"BRL"

​
warnings
string[]

Avisos sobre a query (granularidade indisponível, dados parciais, etc.)