Acquisition

Get Campaigns Table

GET
/v1/acquisition/campaigns

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 whose campaign_id is null;
  • other — only brand and monetization campaigns. Because those are excluded from the CAC numerator, every row of this group has cac: null and ltvCacRatio: null by construction, while newCustomers, avgLtv and roi still 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 reaches utm_campaign and 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 reports null — not 0 — when none of them does. A 0 on either level is a measured zero.
  • The synthetic Campanha não identificada row (one per channel, campaignId: null, synthetic id) carries the customers whose utm_campaign never resolved. It exists only in the acquisition group, has no ad breakdown, and its paybackMonths stays 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.crm null) and their own cpl; 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. leadsBySource splits it by source (CRM / Meta / Google; null for a source the organization does not have) and is null exactly where leads is 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.
  • creativeUrl is only ever populated on ad rows (and may still be null there); it is present and null on the other levels. ad rows carry NO children key at all.
  • Every id is unique across the whole response — the same channel appears in both groups under DIFFERENT ids and no row answers the empty string; see the id field of CampaignRow for the scheme.
  • search filters 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, then adset); 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 in truncation and logged server-side.
  • mql = CRM MQLs + the Meta events picked for the funnel's Qualification stage (V4MOS-2443), the Meta part on Meta Ads campaigns only, split in mqlBySource; campaign and channel rows only. mqlUnavailableReason is null as soon as any source measures the table, and mqlCrmUnavailableReason always carries the CRM's own reason.

Authorization

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Query Parameters

organizationId*string

Organization identifier (required). A missing or non-string value is a 400.

period?stringDeprecated

Deprecated: 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.

Default"30d"
Value in"7d""30d""90d""1y"
startDate?string

Start 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.

Formatdate
endDate?string

End 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.

Formatdate
search?string

Text 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?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.

Formatuuid

Response Body

Campaigns table returned successfully

application/json
  1. response
marginConfigured?boolean

Indicates whether the organization configured a contribution margin on the platform. false means the 100% default is in use.

marginCompleteness?MarginCompleteness

Completeness 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).

Value in"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).

Value in"CRM_NOT_SUPPORTED""QUALIFICATION_NOT_MAPPED"null
mqlCrmUnavailableReason*|

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.

Value in"CRM_NOT_SUPPORTED""QUALIFICATION_NOT_MAPPED"null
curl -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&gtmMotionId=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": []  }}