Pular para o conteúdo

Listar a estrutura de mídia (campanhas, conjuntos e anúncios)

GET
/ad-entities
 
curl --request GET \
  --url 'https://dattacrm.com.br/api/v1/ad-entities?platform=meta&level=campaign&limit=100' \
  --header 'Authorization: Bearer <token>'

Lista a fotografia atual da estrutura de mídia da conta (coletada pelo CRM ou enviada por POST /ad-entities): uma linha por plataforma, nível e entidade, nessa ordem. platform e level filtram. De 1 a 500 registros por página (padrão 100): use nextCursor no parâmetro cursor para a página seguinte; quando vier nulo, acabou. A leitura exige um plano com painel de anúncios (Pro, Max ou Agência); nos outros a chamada é recusada com plan_required (403) e os dados ficam guardados.

Authorizations

Seção intitulada “Authorizations ”

Parameters

Seção intitulada “ Parameters ”

Query Parameters

Seção intitulada “Query Parameters ”
platform

Só esta plataforma: meta, google, tiktok ou linkedin.

string
Allowed values: meta google tiktok linkedin

Só esta plataforma: meta, google, tiktok ou linkedin.

level

Só este nível: campaign, adset ou ad.

string
Allowed values: campaign adset ad

Só este nível: campaign, adset ou ad.

cursor

Cursor da página anterior (nextCursor).

string

Cursor da página anterior (nextCursor).

limit

Registros por página (1 a 500, padrão 100).

integer
default: 100 >= 1 <= 500

Registros por página (1 a 500, padrão 100).

Responses

Seção intitulada “ Responses ”

200

Seção intitulada “200 ”

Sucesso.

Media type application/json
object
data
required

Entidades da página, por plataforma, nível e identificador.

Array<object>

Estado atual de uma campanha, conjunto ou anúncio, como está gravado.

object
level
required

Nível da entidade: campaign (campanha), adset (conjunto de anúncios ou grupo de anúncios) ou ad (anúncio).

string
Allowed values: campaign adset ad
entityId
required

Identificador da entidade na plataforma. Com platform e level, é a chave do registro.

string
>= 1 characters <= 200 characters
name
Any of:
string
<= 500 characters
campaignId
Any of:
string
<= 200 characters
campaignName
Any of:
string
<= 500 characters
adsetId
Any of:
string
<= 200 characters
adsetName
Any of:
string
<= 500 characters
status
Any of:
string
<= 100 characters
effectiveStatus
Any of:
string
<= 100 characters
dailyBudget
Any of:
number
<= 999999999999.99
lifetimeBudget
Any of:
number
<= 999999999999.99
budgetRemaining
Any of:
number
<= 999999999999.99
collectedAt
required

Quando a plataforma foi lida, em ISO 8601 com fuso (ex.: 2026-11-04T13:00:00Z ou 2026-11-04T10:00:00-03:00). Não pode passar de agora mais 10 minutos (400). Um registro com collectedAt mais antigo que o já gravado é ignorado.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
extra

Qualquer outro dado da entidade (objetivo, lance, datas de início e fim etc.), como objeto JSON. Quando enviado, substitui o extra anterior inteiro; quando ausente, o anterior fica.

object
key
additional properties
platform
required

Plataforma da entidade.

string
Allowed values: meta google tiktok linkedin
nextCursor
required

Cursor da próxima página; nulo na última página.

string | null
Example 
{
  "data": [
    {
      "level": "campaign",
      "collectedAt": "2026-11-04T13:00:00Z",
      "platform": "meta"
    }
  ]
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Seção intitulada “400 ”

Dados inválidos na requisição (validation_error): platform ou level desconhecidos, limit fora de 1 a 500 ou cursor inválido.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

401

Seção intitulada “401 ”

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

429

Seção intitulada “429 ”

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After
integer

Segundos até poder tentar de novo.

500

Seção intitulada “500 ”

Erro interno (internal_error). Informe o requestId ao suporte.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.