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

# Conexão com o Meta Ads

> Se a conta tem o Meta Ads conectado, as contas de anúncio e a última leitura do gasto.

#### Escopo

```bash theme={null}
    read analytics
```

O mesmo bloco `metaAds` vem em toda resposta de Analytics; esta rota serve para conferir a conexão sem pedir números. Conectar, reconectar e desconectar ficam no painel, em **Analytics**, no botão **Conectar Meta Ads**.


## OpenAPI

````yaml GET /public_api/analytics/meta-ads/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/analytics/meta-ads/:
    get:
      tags:
        - analytics
      summary: Conexão com o Meta Ads
      description: >-
        Se a conta tem o Meta Ads conectado, as contas de anúncio lidas e até
        quando o gasto foi lido. É o mesmo bloco `metaAds` das outras rotas de
        Analytics. Conectar e desconectar ficam no painel.
      operationId: analytics_meta_ads_status
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsMetaAdsStatus'
              examples:
                Conectado:
                  value:
                    metaAds:
                      connected: true
                      status: active
                      adAccounts:
                        - id: act_123456789
                          name: Conta principal
                          currency: BRL
                      adAccount: null
                      lastSyncedAt: '2026-11-14T09:00:12.481Z'
                Sem conexão:
                  value:
                    metaAds:
                      connected: false
                      status: null
                      adAccounts: []
                      adAccount: null
                      lastSyncedAt: null
          description: ''
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
        '403':
          description: >-
            O token não tem o escopo `analytics`, ou o Cakto Analytics não está
            liberado para a conta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
              examples:
                Analytics não liberado:
                  value:
                    detail: Cakto Analytics não liberado para esta conta.
        '429':
          description: >-
            Passou do limite de 60 consultas por minuto. Espere os segundos do
            cabeçalho `Retry-After`.
      security:
        - OAuth Token: []
components:
  schemas:
    AnalyticsMetaAdsStatus:
      type: object
      properties:
        metaAds:
          $ref: '#/components/schemas/AnalyticsMetaAds'
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    AnalyticsError:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string
          description: >-
            `PRO_REQUIRED` quando a rota é do Cakto Analytics Pro e a conta não
            o tem.
    AnalyticsMetaAds:
      type: object
      description: >-
        Indicador da conexão com o Meta Ads. Vem em toda resposta de Analytics,
        com ou sem conexão.
      properties:
        connected:
          type: boolean
          description: >-
            `true` quando a conta tem o Meta Ads conectado e o custo dos
            anúncios entra nas campanhas. Com `false`, os números de venda vêm
            inteiros e só o custo fica de fora.
        status:
          type: string
          nullable: true
          enum:
            - active
            - expired
            - null
          description: >-
            `active`: a leitura do gasto está em dia. `expired`: o Meta recusou
            o token (venceu, senha trocada, permissão removida) e é preciso
            reconectar no painel; o gasto já lido continua valendo até
            `lastSyncedAt`. `null` sem conexão.
        adAccounts:
          type: array
          description: Contas de anúncio lidas da conexão.
          items:
            $ref: '#/components/schemas/AnalyticsMetaAdAccount'
        adAccount:
          type: string
          nullable: true
          description: >-
            A conta de anúncio filtrada em `adAccount`, quando ela é da conexão.
            `null` = todas.
        lastSyncedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Última leitura do gasto no Meta. O gasto dos três últimos dias é
            relido de hora em hora, porque o Meta ainda o ajusta.
      required:
        - connected
        - status
        - adAccounts
        - adAccount
        - lastSyncedAt
    AnalyticsMetaAdAccount:
      type: object
      properties:
        id:
          type: string
          description: Id da conta de anúncio no Meta (`act_...`).
        name:
          type: string
        currency:
          type: string
          description: Moeda da conta de anúncio (ISO 4217).
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.