Tabela de campanhas
The channel → campaign → adset → ad tree, split into two groups that are ALWAYS both present (even when empty):
acquisition— campaigns classified as acquisition, campaigns with no classification at all, and any media row whosecampaign_idis null;other— onlybrandandmonetizationcampaigns. Because those are excluded from the CAC numerator, every row of this group hascac: nullandltvCacRatio: nullby construction, whilenewCustomers,avgLtvandroistill carry real values.
Row-level rules:
- Media metrics (
investment,impressions,clicks,cpm,ctr,cpc) exist at EVERY level and are computed from that node's own summed raw inputs, never from an average of child ratios. - Business metrics (
roi,newCustomers,cac,avgLtv,ltvCacRatio,paybackMonths) are ALWAYS null below campaign level: attribution reachesutm_campaignand no further. They are never 0, never inherited from the parent, never prorated. - A campaign with no matching totals row gets business metrics
null(unknown), not 0. The same rule applies one level up: a channel row sums the campaigns of it that do have totals and reportsnull— not 0 — when none of them does. A0on either level is a measured zero. - The synthetic
Campanha não identificadarow (one per channel,campaignId: null, syntheticid) carries the customers whoseutm_campaignnever resolved. It exists only in theacquisitiongroup, has no ad breakdown, and itspaybackMonthsstays null on purpose — showing the channel's figure there would be inventing a number. - A campaign that acquired customers in the window but spent nothing in it is emitted too, with zero media and therefore null media ratios.
leads= CRM leads by UTM (V4MOS-1910) + the platform leads the organization's funnel counts on its Interest stage (Meta events / Google Ads lead categories, by the platform's own campaign id). Adset/ad rows (V4MOS-2443) carry the platform leads of that node only (leadsBySource.crmnull) and their owncpl; Performance Max and nodes without a platform id stay null. Null everywhere only when the organization has neither lead source. The channel row sums the campaigns shown, like its media.leadsBySourcesplits it by source (CRM / Meta / Google; null for a source the organization does not have) and is null exactly whereleadsis null;leads= round2 of the sum of its non-null parts, and a channel's breakdown is the per-source sum of its campaigns shown.creativeUrlis only ever populated onadrows (and may still be null there); it is present and null on the other levels.adrows carry NOchildrenkey at all.- Every
idis unique across the whole response — the same channel appears in both groups under DIFFERENT ids and no row answers the empty string; see theidfield ofCampaignRowfor the scheme. searchfilters which campaigns/channels APPEAR (matching campaign, adset or ad name, case-insensitively, plus the label of the unattributed row) and which adset/ad children are displayed, but never shrinks the own aggregate of a campaign that survived the filter. A channel's own aggregate covers only the campaigns still displayed, so while a search is active the table does not reconcile with the channel card.- The response is capped at 5000 rows across both groups. The cap drops the DEEPEST levels first (
ad, thenadset); channels and campaigns are never dropped, so a tree that exceeds the cap on those levels alone is returned in full and still flagged. Truncation is always reported intruncationand logged server-side. mql= CRM MQLs + the Meta events picked for the funnel's Qualification stage (V4MOS-2443), the Meta part onMeta Adscampaigns only, split inmqlBySource; campaign and channel rows only.mqlUnavailableReasonis null as soon as any source measures the table, andmqlCrmUnavailableReasonalways carries the CRM's own reason.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringIdentificador da organização (obrigatório). Um valor ausente ou que não seja string resulta em 400.
period?stringDescontinuadoDescontinuado: 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.
"30d""7d""30d""90d""1y"startDate?stringIní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.
dateendDate?stringFim 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.
datesearch?stringFiltro de texto pelo nome da campanha, do conjunto de anúncios ou do anúncio, sem diferenciar maiúsculas de minúsculas (também encontra Campanha não identificada). Vazio não filtra. Só /v1/acquisition/campaigns usa este parâmetro; os demais endpoints o aceitam e ignoram.
gtmMotionId?stringGTM 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.
uuidTabela de campanhas retornada com sucesso
application/json- response
marginConfigured?booleanIndica se a organização configurou uma margem de contribuição na plataforma. false significa que o padrão de 100% está em uso.
marginCompleteness?MarginCompletenessCompletude da margem de contribuição configurada por itens de custo: complete = todos os itens resolvidos; partial = algum item pendente, então a margem aplicada é parcial; none = sem composição por itens (margem nunca configurada ou configurada como um percentual único; diferencie com marginConfigured).
"complete""partial""none"marginItemStatus?Status por item da composição da margem (synced = vindo dos pedidos, configured = informado pelo usuário, pending = não configurado ou com dados ausentes). null quando a organização não tem composição.
groups*array<>Sempre exatamente dois grupos, nesta ordem: acquisition e other. Os dois são retornados mesmo quando vazios.
truncation*Informa se a tabela foi cortada pelo limite de linhas, para você poder exibir "mostrando N de M linhas" em vez de uma árvore incompleta sem aviso.
mqlUnavailableReason*|Why mql and cpmql are null on EVERY row. Null as soon as any MQL source measures the table — the CRM (obt_cpl_daily.mql_status = SUPPORTED) or the Meta events picked for the funnel's Qualification stage (V4MOS-2443) — and null too when nothing could be read (a CRM MQL read failed, or mql_status holds an unknown value: then every row is null with no reason). Otherwise the CRM's reason: CRM_NOT_SUPPORTED (only HubSpot produces MQLs this round; also an organization with no obt_cpl_daily row at all) or QUALIFICATION_NOT_MAPPED (HubSpot connected, qualification stage not mapped).
"CRM_NOT_SUPPORTED""QUALIFICATION_NOT_MAPPED"nullmqlCrmUnavailableReason*|The CRM half of mqlUnavailableReason, whatever the Meta events (V4MOS-2443): why the CRM part of the MQL (mqlBySource.crm) is not measured. With Meta Qualification events and no supported CRM, mqlUnavailableReason is null and this field explains the null mql of the non-Meta rows. Null when the CRM measures MQLs or when nothing could be read.
"CRM_NOT_SUPPORTED""QUALIFICATION_NOT_MAPPED"nullcurl -X GET "https://example.com/v1/acquisition/campaigns?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&period=30d&startDate=2026-03-11&endDate=2026-03-22&search=prospec%C3%A7%C3%A3o>mMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"{ "groups": [ { "groupId": "acquisition", "rows": [ { "level": "channel", "id": "v4:acquisition:channel:Meta%20Ads", "name": "Meta Ads", "campaignId": null, "creativeUrl": null, "investment": 128000, "impressions": 10000000, "clicks": 195000, "cpm": 12.8, "ctr": 1.95, "cpc": 0.66, "leads": 4838, "leadsBySource": { "crm": 4838, "meta": null, "google": null }, "roi": 1.94, "newCustomers": 1120, "cac": 114.29, "avgLtv": 486.5, "ltvCacRatio": 4.26, "paybackMonths": 2.7, "children": [ { "level": "campaign", "id": "cmp-8891", "name": "Aquisição | Prospecção BR", "campaignId": "cmp-8891", "creativeUrl": null, "investment": 96000, "impressions": 7680000, "clicks": 161280, "cpm": 12.5, "ctr": 2.1, "cpc": 0.6, "leads": 4838, "leadsBySource": { "crm": 4838, "meta": null, "google": null }, "roi": 2.31, "newCustomers": 940, "cac": 102.13, "avgLtv": 501.2, "ltvCacRatio": 4.91, "paybackMonths": 2.4, "children": [ { "level": "adset", "id": "adset-11", "name": "Conjunto Lookalike 1%", "campaignId": null, "creativeUrl": null, "investment": 51000, "impressions": 4214876, "clicks": 96942, "cpm": 12.1, "ctr": 2.3, "cpc": 0.53, "leads": 4, "leadsBySource": { "crm": null, "meta": 4, "google": null }, "roi": null, "newCustomers": null, "cac": null, "avgLtv": null, "ltvCacRatio": null, "paybackMonths": null, "children": [ { "level": "ad", "id": "ad-101", "name": "Vídeo institucional 15s", "campaignId": null, "creativeUrl": "https://cdn.example.com/creative/ad-101.jpg", "investment": 51000, "impressions": 4214876, "clicks": 96942, "cpm": 12.1, "ctr": 2.3, "cpc": 0.53, "leads": 2, "leadsBySource": { "crm": null, "meta": 2, "google": null }, "roi": null, "newCustomers": null, "cac": null, "avgLtv": null, "ltvCacRatio": null, "paybackMonths": null, "cpl": 25500 } ], "cpl": 12750 } ] }, { "level": "campaign", "id": "v4:acquisition:unknown-campaign:Meta%20Ads", "name": "Campanha não identificada", "campaignId": null, "creativeUrl": null, "investment": 0, "impressions": 0, "clicks": 0, "cpm": null, "ctr": null, "cpc": null, "leads": 0, "leadsBySource": { "crm": 0, "meta": null, "google": null }, "roi": null, "newCustomers": 180, "cac": null, "avgLtv": 412.7, "ltvCacRatio": null, "paybackMonths": null, "children": [] } ] } ] }, { "groupId": "other", "rows": [] } ], "truncation": { "truncated": false, "returnedRows": 5, "totalRows": 5, "droppedLevels": [] }}