Consultar Métricas

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"
}

POST

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:

JWT da plataforma
- Header: Authorization: Bearer {jwt}
- Header adicional obrigatório: X-Workspace-Id
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é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

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

Show child attributes

filters

object[]

Filtros para restringir os dados retornados

Show child attributes

order

object

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

Show child attributes

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

Show child attributes

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.)

Listar campos disponíveis Obter Container

Visão Geral

Plataforma

API de Dados

API de Rastreamento

Consultar Métricas

Autenticação

Métricas Disponíveis

Métricas Base (sincronizadas das APIs)

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

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

Métricas Calculadas — Atribuição de Vendas

Métricas Calculadas — Financeiro

Granularidades

Conversão de Moeda

Authorizations

Headers

Body

Response

​Autenticação

​Métricas Disponíveis

​Métricas Base (sincronizadas das APIs)

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

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

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

​Métricas Calculadas — Financeiro

​Granularidades

​Conversão de Moeda

Authorizations

Headers

Body

Response

Autenticação

Métricas Disponíveis

Métricas Base (sincronizadas das APIs)

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

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

Métricas Calculadas — Atribuição de Vendas

Métricas Calculadas — Financeiro

Granularidades

Conversão de Moeda