Get Campaigns Table
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*stringOrganization identifier (required). A missing or non-string value is a 400.
period?stringDeprecatedDeprecated: use startDate and endDate, which take precedence when sent. Relative period of N days ending today, inclusive (7d = today and the 6 days before it). "Today" is the UTC calendar day, and that last day is still partial. Accepted values: 7d, 30d, 90d, 1y. Omitted or empty means 30d; any other value returns 400.
"30d""7d""30d""90d""1y"startDate?stringStart of the period (YYYY-MM-DD, inclusive). Send it together with endDate: sending only one of them returns 400. Takes precedence over period. Send the date only: a date with a time or a date that does not exist returns 400. Rules: startDate ≤ endDate, neither date in the future (UTC), and at most 365 days between the dates (up to 366 days in the period). The comparison uses the period of the same length right before it.
dateendDate?stringEnd of the period (YYYY-MM-DD, inclusive). See startDate for the rules. When the end date is today, that last day is still partial, because the day's data keeps arriving.
datesearch?stringText filter on campaign, ad set or ad name, case-insensitive (it also matches Campanha não identificada). Empty means no filter. Only /v1/acquisition/campaigns uses this parameter; the other endpoints accept and ignore it.
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.
uuidCampaigns table returned successfully
application/json- response
marginConfigured?booleanIndicates whether the organization configured a contribution margin on the platform. false means the 100% default is in use.
marginCompleteness?MarginCompletenessCompleteness of the contribution margin configured by cost item: complete = every item resolved; partial = some item is pending, so the applied margin is partial; none = no item breakdown (margin never configured, or configured as a single percentage; tell them apart with marginConfigured).
"complete""partial""none"marginItemStatus?Status per item of the margin composition (synced = from the orders, configured = informed by the user, pending = not configured or missing data). null when the organization has no composition.
groups*array<>Always exactly two groups, in this order: acquisition, then other. Both are returned even when empty.
truncation*Tells whether the table was cut by the row limit, so you can show "showing N of M rows" instead of an incomplete tree with no warning.
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": [] }}