Aquisição

Visão geral da mídia paga

GET
/v1/acquisition/paid-media

Cards and daily series of the Mídia Paga › Visão Geral screen. Paid channels only — every media channel of the acquisition fact (Meta Ads, Google Ads, LinkedIn Ads, TikTok Ads, Pinterest Ads, Microsoft Ads, OpenAI Ads; V4MOS-1584): Orgânico has no spend, and its leads are not paid leads. Platform-reported leads and reach stay Meta/Google only.

Source: analytics.obt_cpl_daily (V4MOS-1910), in the grain of the acquisition fact — investment, impressions and clicks from the same media fact as /campaigns, and CRM leads (HubSpot, Kommo, CRM V4) under the Interest-stage rule, credited to a paid channel by UTM. leads ADDS the platform-reported leads the organization's funnel counts on its Interest stage, exactly as the funnel does (CRM + Meta + Google): the Meta events picked for Meta Ads on the Interest row (default lead, from facebook_ads_actions) and the Google Ads conversion categories picked there (default SUBMIT_LEAD_FORM, IMPORTED_LEAD, PHONE_CALL_LEAD, from google_ads_conversion_segmented_campaigns). A platform only counts when the funnel would count it: selected on the Interest row, business model inside_sales or pdv, Interest not fed by a spreadsheet. A CRM lead that came from a Meta form with a paid UTM is counted on both sides — accepted, it is the funnel's own rule.

Rules:

  • Every card carries the relative change against the immediately preceding window of the same length, like /summary.
  • cpl = Σ investment ÷ Σ leads over the window — never an average of the daily CPLs. Null (never 0) without a lead or without spend.
  • hasLeadSource: false means neither source exists: no lead of this organization was ever credited to a paid channel (no CRM, or CRM leads that never carry a paid UTM) AND no platform lead the funnel counts on Interest was ever recorded (no Meta/Google on the Interest row, or selected but no matching event in the warehouse). Then leads and cpl are null on the cards AND on every day — not measured, not 0. With a lead source, a day or window with no lead is a real 0.
  • daily has one point per calendar day of the window, in order. A day with no warehouse row is a measured zero of spend, so the series never has holes.
  • leadsBySource (top level and on each daily point) splits leads by source: crm, meta, google. A source the organization does not have is null; an active source with no lead is 0. Null exactly when hasLeadSource is false. Invariant: leads = round2((crm ?? 0) + (meta ?? 0) + (google ?? 0)).
  • reach (card and each daily point) is Meta-only people reached, summed per day and campaign: an approximation that over-counts people reached on several days/campaigns. Null when the organization has no Meta data at all; 0 when Meta is measured with no reach.
  • The cards are the sum of daily, so the two always reconcile.

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
gtmMotionId?string

GTM motion of the organization (UUID, as gtm_motions.id), V4MOS-2707. Omitted, or the default motion of the organization: the organization numbers, exactly as before. Another motion of the organization: /v1/acquisition/paid-media answers with that motion's own rows (investment, impressions, clicks, CRM leads and CPL from analytics.obt_cpl_daily_by_gtm_motion; Meta/Google platform leads and Meta reach are null, they have no motion grain yet); every other acquisition route answers 422 GTM_MOTION_DATA_NOT_AVAILABLE. Not a UUID: 400. Not a live motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.

Formatouuid

Corpo da resposta

Visão geral de mídia paga retornada com sucesso

application/json
  1. response

Mídia Paga › Visão Geral: paid-media cards (every media channel, Orgânico excluded) with change vs the previous window, and the day-by-day series behind them.

investment*

Valor de uma métrica mais a variação relativa contra o período anterior. changePct vem null quando não pode ser calculado (um dos lados null ou valor anterior igual a 0). Nesse caso, não exiba a variação.

impressions*

Valor de uma métrica mais a variação relativa contra o período anterior. changePct vem null quando não pode ser calculado (um dos lados null ou valor anterior igual a 0). Nesse caso, não exiba a variação.

reach*

Pessoas alcançadas no Meta Ads (o Google Ads não reporta alcance). É uma aproximação: o Meta informa pessoas únicas por campanha e por dia, e este valor soma esses números, então quem foi alcançado em vários dias ou por várias campanhas conta mais de uma vez. value é null quando a organização não tem dados do Meta Ads ou o alcance não pôde ser lido; 0 quando o Meta é medido e não alcançou ninguém.

clicks*

Valor de uma métrica mais a variação relativa contra o período anterior. changePct vem null quando não pode ser calculado (um dos lados null ou valor anterior igual a 0). Nesse caso, não exiba a variação.

leads*

Valor de uma métrica mais a variação relativa contra o período anterior. changePct vem null quando não pode ser calculado (um dos lados null ou valor anterior igual a 0). Nesse caso, não exiba a variação.

leadsBySource*|

leads.value da janela dividido por fonte. Sem variação em relação à janela anterior. Null exatamente quando hasLeadSource é false.

cpl*

Valor de uma métrica mais a variação relativa contra o período anterior. changePct vem null quando não pode ser calculado (um dos lados null ou valor anterior igual a 0). Nesse caso, não exiba a variação.

hasLeadSource*boolean

Indica se a organização tem QUALQUER fonte de lead, independentemente da janela: um lead do CRM jamais creditado a um canal pago, OU um lead de plataforma (evento do Meta / categoria de lead do Google) jamais registrado sob a configuração de Interesse do funil. False = nenhuma das duas: leads e CPL não são medidos (null), não zero.

daily*array<>

One point per calendar day of the window, oldest first, no gaps — one point per calendar month (date = YYYY-MM) when periodApplied.granularity is monthly (all mode).

periodApplied?

The window actually read (V4MOS-2404). mode: range for a preset or a typed interval: daily series, changePct against the same-length window before. mode: all — only via POST /v1/analytics/query with filters.period = { mode: 'all' } — for [the organization's first date with data, today]: granularity: monthly, daily[] holds one point per month (date = YYYY-MM), every changePct is null and no previous window is read. In all the warehouse groups each source by calendar month (one row per month, never one per day); the additive cards (investment, impressions, clicks, leads) equal the sum of the monthly points, cpl is Σ investment ÷ Σ leads, and reach is the card only (the same sum-of-daily-reach approximation over the whole window, read as one total) with null on every point.

curl -X GET "https://example.com/v1/acquisition/paid-media?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&period=30d&startDate=2026-03-11&endDate=2026-03-22&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"

{  "investment": {    "value": 11300,    "changePct": 8.4  },  "impressions": {    "value": 1250000,    "changePct": 3.1  },  "reach": {    "value": 123200,    "changePct": 4.2  },  "clicks": {    "value": 18400,    "changePct": -1.2  },  "leads": {    "value": 412,    "changePct": 12.6  },  "leadsBySource": {    "crm": 300,    "meta": 100,    "google": 12  },  "cpl": {    "value": 27.43,    "changePct": -3.73  },  "hasLeadSource": true,  "daily": [    {      "date": "2026-09-01",      "investment": 3800,      "impressions": 420000,      "reach": 61000,      "clicks": 6100,      "leads": 140,      "leadsBySource": {        "crm": 100,        "meta": 35,        "google": 5      },      "cpl": 27.14    },    {      "date": "2026-09-02",      "investment": 0,      "impressions": 0,      "reach": 0,      "clicks": 0,      "leads": 0,      "leadsBySource": {        "crm": 0,        "meta": 0,        "google": 0      },      "cpl": null    },    {      "date": "2026-09-03",      "investment": 7500,      "impressions": 830000,      "reach": 62200,      "clicks": 12300,      "leads": 272,      "leadsBySource": {        "crm": 200,        "meta": 65,        "google": 7      },      "cpl": 27.57    }  ],  "periodApplied": {    "mode": "range",    "startDate": "2026-09-01",    "endDate": "2026-09-03",    "granularity": "daily"  }}