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

# Listar Campos Disponíveis

> Retorna a lista de todas as métricas e dimensões disponíveis para consulta,
com metadados como nome, descrição, tipo de dado e fontes suportadas.

**Autenticação obrigatória** em `api.metrito.com`:

- **JWT** — `Authorization: Bearer {jwt}` e header `X-Workspace-Id`
- **API Key** — `Authorization: Bearer mtk_live_...` ou header `x-api-key` (workspace resolvido pela chave; `X-Workspace-Id` não é necessário)

Requer escopo `data:read` quando usar API Key.




## OpenAPI

````yaml /openapi/data.yaml get /v3/fields
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/fields:
    get:
      summary: Listar campos disponíveis
      description: >
        Retorna a lista de todas as métricas e dimensões disponíveis para
        consulta,

        com metadados como nome, descrição, tipo de dado e fontes suportadas.


        **Autenticação obrigatória** em `api.metrito.com`:


        - **JWT** — `Authorization: Bearer {jwt}` e header `X-Workspace-Id`

        - **API Key** — `Authorization: Bearer mtk_live_...` ou header
        `x-api-key` (workspace resolvido pela chave; `X-Workspace-Id` não é
        necessário)


        Requer escopo `data:read` quando usar API Key.
      operationId: listFields
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: Lista de campos retornada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldsResponse'
              example:
                fields:
                  - key: spend
                    name: Investimento
                    short_name: Invest.
                    description: Valor gasto em anúncios
                    type: measure
                    data_type: currency
                    display_type: currency
                    source_key: v3-ads
                    sources:
                      - meta_ads
                      - google_ads
                      - tiktok_ads
                    good_direction: down
                    available: true
                    filterable: true
                    sortable: true
                  - key: ctr
                    name: CTR
                    short_name: CTR
                    description: Taxa de clique (clicks / impressions)
                    type: measure
                    data_type: percentage
                    display_type: percentage
                    source_key: v3-ads
                    sources:
                      - meta_ads
                      - google_ads
                      - tiktok_ads
                    good_direction: up
                    available: true
                    filterable: false
                    sortable: true
                count: 2
                source: v3-ads
                timestamp: '2026-03-15T12:00:00.000Z'
        '401':
          description: Credencial ausente, inválida, revogada ou expirada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: authentication_error
                  code: invalid_credentials
                  message: Você não está autenticado para isso.
                  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:
    FieldsResponse:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        count:
          type: integer
          description: Total de campos retornados
        source:
          type: string
          description: Identificador da fonte de campos
          example: v3-ads
        timestamp:
          type: string
          format: date-time
    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
    Field:
      type: object
      properties:
        key:
          type: string
          description: Identificador único do campo (usar na query)
          example: spend
        name:
          type: string
          description: Nome legível
          example: Investimento
        short_name:
          type: string
          description: Nome curto para tabelas
          example: Invest.
        description:
          type: string
          description: Descrição do campo
        type:
          type: string
          enum:
            - measure
            - dimension
          description: Tipo do campo
        data_type:
          type: string
          description: Tipo de dado (currency, percentage, number, string, etc.)
        display_type:
          type: string
          description: Como exibir o valor na UI
        source_key:
          type: string
        sources:
          type: array
          items:
            type: string
          description: >-
            Plataformas que suportam este campo (meta_ads, google_ads,
            tiktok_ads)
        good_direction:
          type: string
          enum:
            - up
            - down
          description: >-
            Direção positiva do valor (up = maior é melhor, down = menor é
            melhor)
        available:
          type: boolean
        filterable:
          type: boolean
        sortable:
          type: boolean
  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`

````