> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrito.com/llms.txt
> Use this file to discover all available pages before exploring further.

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


## 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é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.


## OpenAPI

````yaml /openapi/data.yaml post /v3/query
openapi: 3.1.0
info:
  title: API de Dados — Metrito
  version: '3.0'
  description: >
    API para consulta de métricas de anúncios sincronizadas das plataformas
    (Meta Ads, Google Ads, TikTok Ads).

    Os dados são sincronizados automaticamente em background e ficam disponíveis
    para consulta via esta API.


    ## Novidades na v3


    - Endpoints auxiliares por conexão (`/v3/connections/:id/`) em preparação
    para a doc pública

    - Rate limiting com headers `X-RateLimit-*`

    - Request ID via `X-Request-Id` em todas as respostas

    - Formato de erro padronizado
servers:
  - url: https://api.metrito.com
    description: Produção
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v3/query:
    post:
      summary: Consultar métricas de anúncios
      description: >
        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.
      operationId: queryMetrics
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
            examples:
              aggregated:
                summary: Totais agregados (sem breakdown)
                value:
                  project_id: 69162064162b926ae607959b
                  fields:
                    - spend
                    - impressions
                    - clicks
                  time:
                    start: '2026-02-01'
                    end: '2026-02-08'
              byCampaign:
                summary: Por campanha com granularidade diária
                value:
                  project_id: 69162064162b926ae607959b
                  fields:
                    - spend
                    - impressions
                    - clicks
                    - ctr
                    - cpc
                  time:
                    start: '2026-02-01'
                    end: '2026-02-08'
                    granularity: day
                  metadata:
                    level: campaign
              byAd:
                summary: Por anúncio de uma plataforma
                value:
                  project_id: 69162064162b926ae607959b
                  source: meta_ads
                  fields:
                    - spend
                    - impressions
                    - clicks
                    - ctr
                    - hook_rate
                    - hold_rate
                  time:
                    start: '2026-02-08'
                    end: '2026-02-08'
                  metadata:
                    level: ad
              withCurrency:
                summary: Com conversão de moeda explícita
                value:
                  project_id: 69162064162b926ae607959b
                  fields:
                    - spend
                    - roas
                    - tx_revenue
                    - profit
                  time:
                    start: '2026-02-01'
                    end: '2026-02-08'
                  metadata:
                    convert_to_currency: USD
      responses:
        '200':
          description: Dados retornados com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                success: true
                data:
                  - spend: 1250.75
                    impressions: 45230
                    clicks: 1205
                    ctr: 0.0266
                    cpc: 1.038
                currency: BRL
        '400':
          description: Erro de validação na query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingField:
                  summary: Campo obrigatório ausente
                  value:
                    error:
                      type: validation_error
                      code: invalid_parameter
                      message: project_id is required
                      details:
                        - project_id is required
                      request_id: req_abc123
                invalidSource:
                  summary: Source inválido
                  value:
                    error:
                      type: validation_error
                      code: invalid_source
                      message: >-
                        Unknown source: invalid. Valid sources: meta_ads,
                        google_ads, tiktok_ads
                      request_id: req_abc123
        '401':
          description: Credencial ausente, inválida, revogada ou expirada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: The API key provided is invalid or has been revoked.
                  request_id: req_abc123
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  parameters:
    WorkspaceId:
      name: X-Workspace-Id
      in: header
      required: false
      description: >-
        Obrigatório quando usar JWT. Opcional quando usar API key
        (`mtk_live_...`)
      schema:
        type: string
        example: 69162064162b926ae607959b
  schemas:
    QueryRequest:
      type: object
      required:
        - project_id
        - fields
      properties:
        project_id:
          type: string
          description: ID do projeto (brand) no Metrito
          example: 69162064162b926ae607959b
        fields:
          type: array
          items:
            type: string
          minItems: 1
          description: >-
            Lista de métricas a consultar. Consulte `GET /v3/fields` para ver
            todas as opções.
          example:
            - spend
            - impressions
            - clicks
            - ctr
        source:
          type: string
          description: Plataforma de anúncios. Omita para consultar todas.
          enum:
            - meta_ads
            - google_ads
            - tiktok_ads
          example: meta_ads
        connection_ids:
          type: array
          items:
            type: string
          description: >-
            IDs de conexões específicas. Omita para usar todas as conexões do
            projeto.
        time:
          $ref: '#/components/schemas/TimeRange'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
          description: Filtros para restringir os dados retornados
        order:
          type: object
          additionalProperties:
            type: string
            enum:
              - asc
              - desc
          description: 'Ordenação dos resultados. Ex: `{ "spend": "desc" }`'
          example:
            spend: desc
        limit:
          type: integer
          minimum: 1
          maximum: 50000
          description: Limite de resultados
          example: 100
        offset:
          type: integer
          minimum: 0
          description: Offset para paginação
        metadata:
          $ref: '#/components/schemas/QueryMetadata'
    QueryResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Resultados da query. Cada item contém as métricas solicitadas.
        currency:
          type: string
          description: Moeda dos valores monetários na resposta
          example: BRL
        warnings:
          type: array
          items:
            type: string
          description: >-
            Avisos sobre a query (granularidade indisponível, dados parciais,
            etc.)
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - authorization_error
                - validation_error
                - not_found_error
                - api_error
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: string
              nullable: true
            request_id:
              type: string
              nullable: true
        warnings:
          type: array
          items:
            type: string
          nullable: true
    TimeRange:
      type: object
      required:
        - start
        - end
      properties:
        start:
          type: string
          description: Data inicial (YYYY-MM-DD ou ISO datetime)
          example: '2026-02-01'
        end:
          type: string
          description: Data final (YYYY-MM-DD ou ISO datetime)
          example: '2026-02-08'
        granularity:
          type: string
          enum:
            - 5min
            - 10min
            - 15min
            - 30min
            - hour
            - day
            - week
            - month
            - quarter
            - year
          description: >-
            Granularidade temporal. Omita para retornar totais agregados sem
            breakdown.
          example: day
    Filter:
      type: object
      required:
        - member
        - operator
      properties:
        member:
          type: string
          description: Nome do campo a filtrar
          example: campaign_id
        operator:
          type: string
          enum:
            - equals
            - notEquals
            - contains
            - notContains
            - startsWith
            - endsWith
            - gt
            - gte
            - lt
            - lte
            - set
            - notSet
          description: Operador de comparação
          example: equals
        values:
          type: array
          items:
            type: string
          description: Valores para comparação (obrigatório exceto para `set`/`notSet`)
          example:
            - '120239000000000'
    QueryMetadata:
      type: object
      description: Opções adicionais da query
      properties:
        level:
          type: string
          enum:
            - account
            - campaign
            - adset
            - ad
          description: >-
            Nível de agrupamento hierárquico. Omita para retornar totais sem
            breakdown por entidade.
          example: campaign
        convert_to_currency:
          type: string
          description: >-
            Forçar conversão para moeda específica (ISO 4217). Ignora a moeda
            padrão do projeto.
          example: USD
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or API Key
      description: >-
        JWT da plataforma ou API key `mtk_live_...` enviada no header
        Authorization
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key `mtk_live_...` enviada via header `x-api-key`

````