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"
}Consultar Métricas
Endpoint unificado para consulta de métricas de anúncios. Retorna dados sincronizados do PostgreSQL via CubeJS, com enriquecimento de nomes de entidades e conversão de moeda automática.
Os dados são sincronizados em background a cada 5-30 minutos (conforme o tier do plano). A resposta é instantânea (~50ms) pois consulta dados já armazenados localmente.
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:-
JWT da plataforma
- Header:
Authorization: Bearer {jwt} - Header adicional obrigatório:
X-Workspace-Id
- Header:
-
API Key do Metrito
- Header:
Authorization: Bearer mtk_live_...oux-api-key: mtk_live_... - Não precisa enviar
X-Workspace-Id(o workspace é resolvido pela própria chave)
- Header:
Métricas Disponíveis
Métricas Base (sincronizadas das APIs)
| Métrica | Descrição |
|---|---|
spend | Valor gasto em anúncios |
impressions | Vezes que o anúncio foi exibido |
clicks | Cliques no anúncio |
reach | Pessoas únicas alcançadas (apenas Meta) |
video_plays | Vezes que o vídeo começou a rodar |
video_views_p75 | Visualizações até 75% do vídeo |
Métricas Calculadas — Eficiência de Tráfego
| Métrica | Fórmula | Descrição |
|---|---|---|
ctr | clicks / impressions | Taxa de clique |
cpc | spend / clicks | Custo por clique |
cpm | (spend / impressions) * 1000 | Custo por mil impressões |
frequency | impressions / reach | Frequência média |
Métricas Calculadas — Análise de Vídeo
| Métrica | Fórmula | Descrição |
|---|---|---|
hook_rate | video_views_3s / impressions | Qualidade do hook (3s) |
hold_rate | video_views_p75 / impressions | Qualidade do conteúdo (75%) |
play_rate | video_plays / impressions | Taxa de play |
cta_rate | clicks / video_views_p75 | Eficácia do CTA |
Métricas Calculadas — Atribuição de Vendas
| Métrica | Descrição |
|---|---|
tx_revenue | Faturamento atribuído |
tx_count | Vendas aprovadas |
tx_count_total | Vendas totais (inclui pendentes) |
tx_count_pending | Vendas pendentes |
tx_count_refunded | Reembolsos |
page_views | Visualizações de página |
leads | Cadastros/leads |
initiate_checkout | Inícios de checkout |
Métricas Calculadas — Financeiro
| Métrica | Fórmula | Descrição |
|---|---|---|
roas | tx_revenue / spend | Retorno sobre investimento em ads |
roi | (tx_revenue - spend) / spend | ROI percentual |
profit | tx_revenue - spend - tx_product_costs | Lucro líquido |
aov | tx_revenue / tx_count | Ticket médio |
cpa | spend / tx_count | Custo por aquisição |
cpl | spend / leads | Custo por lead |
Granularidades
| Valor | Descrição |
|---|---|
5min, 10min, 15min, 30min | Sub-horária (planos Growth/Enterprise) |
hour | Horária |
day | Diária |
week | Semanal |
month | Mensal |
quarter | Trimestral |
year | Anual |
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, usemetadata.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.Autorizações
JWT da plataforma ou API key mtk_live_... enviada no header Authorization
Cabeçalhos
Obrigatório quando usar JWT. Opcional quando usar API key (mtk_live_...)
"69162064162b926ae607959b"
Corpo
ID do projeto (brand) no Metrito
"69162064162b926ae607959b"
Lista de métricas a consultar. Consulte GET /v3/fields para ver todas as opções.
1["spend", "impressions", "clicks", "ctr"]
Plataforma de anúncios. Omita para consultar todas.
meta_ads, google_ads, tiktok_ads "meta_ads"
IDs de conexões específicas. Omita para usar todas as conexões do projeto.
Show child attributes
Show child attributes
Filtros para restringir os dados retornados
Show child attributes
Show child attributes
Ordenação dos resultados. Ex: { "spend": "desc" }
Show child attributes
Show child attributes
{ "spend": "desc" }
Limite de resultados
1 <= x <= 50000100
Offset para paginação
x >= 0Opções adicionais da query
Show child attributes
Show child attributes