V4MOS.AI API
GuiasReferência da APIapp.v4mos.ai
Aquisição

Público da mídia paga

GET
/v1/acquisition/paid-media/audience

Público e região da mídia do Meta Ads: investimento, leads e custo por lead por gênero e faixa etária, e alcance e custo por região.

Use para entender quem os anúncios do Meta alcançam e onde. Só Meta Ads.

  • Os leads são o evento lead do Meta, sem a seleção de eventos do funil. Por isso não batem com /v1/acquisition/paid-media, que também soma leads do CRM e do Google Ads.
  • genders traz sempre female, male e unknown, nessa ordem. ages lista as faixas etárias com investimento ou lead, da mais jovem para a mais velha, com unknown por último.
  • regions lista as regiões (estados) com alcance, da mais alcançada para a menos alcançada. O alcance é uma aproximação somada por anúncio e dia, e as regiões não trazem leads.
  • hasMeta: false: a organização não tem dados do Meta Ads e as listas vêm vazias. hasLeads: false: os dados do período não trazem leads, então leads, cpl e leadsByGender vêm null.

Autorização

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Parâmetros de query

organizationId*string

Identificador da organização (obrigatório). Um valor ausente ou que não seja string resulta em 400.

period?stringDescontinuado

Descontinuado: use startDate e endDate, que têm precedência quando enviados. Período relativo de N dias terminando hoje, inclusive (7d = hoje e os 6 dias anteriores). "Hoje" é o dia de calendário em UTC, e esse último dia ainda está parcial. Valores aceitos: 7d, 30d, 90d, 1y. Omitido ou vazio equivale a 30d; qualquer outro valor retorna 400.

Padrão"30d"
Valor em"7d""30d""90d""1y"
startDate?string

Início do período (YYYY-MM-DD, inclusivo). Envie junto com endDate: enviar só um dos dois retorna 400. Tem precedência sobre period. Use só a data: data com hora ou data inexistente retorna 400. Regras: startDate ≤ endDate, nenhuma data no futuro (UTC) e no máximo 365 dias entre as datas (até 366 dias no período). A comparação usa o período de mesma duração imediatamente anterior.

Formatodate
endDate?string

Fim do período (YYYY-MM-DD, inclusivo). Veja startDate para as regras. Quando o fim é hoje, esse último dia ainda está parcial, porque os dados do dia continuam chegando.

Formatodate

Corpo da resposta

Público e região de mídia paga retornado com sucesso

application/json
  1. response
hasMeta*boolean
hasLeads*boolean
genders*array<>
ages*array<>
regions*array<>
curl -X GET "https://example.com/v1/acquisition/paid-media/audience?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&period=30d&startDate=2026-03-11&endDate=2026-03-22"
{  "hasMeta": true,  "hasLeads": true,  "genders": [    {      "gender": "female",      "investment": 5238.38,      "leads": 217,      "cpl": 24.14    },    {      "gender": "male",      "investment": 5856.58,      "leads": 206,      "cpl": 28.43    },    {      "gender": "unknown",      "investment": 28.44,      "leads": 2,      "cpl": 14.22    }  ],  "ages": [    {      "ageRange": "18-24",      "investment": 182.36,      "leads": 4,      "cpl": 45.59,      "leadsByGender": {        "female": 1,        "male": 3,        "unknown": 0      }    },    {      "ageRange": "65+",      "investment": 1662.86,      "leads": 94,      "cpl": 17.69,      "leadsByGender": {        "female": 52,        "male": 42,        "unknown": 0      }    }  ],  "regions": [    {      "region": "São Paulo",      "country": "BR",      "reach": 26300,      "investment": 2766.5,      "costPerThousandReach": 105.19    }  ]}

Visão geral da mídia paga GET

Página anterior