Acquisition

Get Gain-Flow Funnel

GET
/v1/acquisition/funnel

The "Fluxo de ganho" block. Since V4MOS-1255 it is served by the product's existing bottleneck funnel (BottleneckFunnelRepository.getConversionFunnel, the same funnel that backs Destrava Receita) rather than by a distinct-customer count of its own.

Consequences the client must handle:

  • Only the stages the organization CONFIGURED in organization_bottleneck_config are returned. An organization with no bottleneck configuration gets stages: [] — an empty block, not a six-stage funnel of zeros.
  • When the organization configured bottlenecks but no data source could produce an execution plan, every upstream stage value is null; that all-null case is collapsed to stages: [] as well. A PARTIALLY null result keeps the ordinary ?? 0 coalescing, so one stage may legitimately read count: 0 while its neighbours carry real values.
  • The RETENCAO stage of the bowtie is dropped: it is not one of the six stages of this screen.
  • count is SUMMED EVENT VOLUME, not distinct people: EXPOSURE = impressions, ATTENTION = clicks + GA4 sessions, INTEREST = leads + add-to-cart, QUALIFICATION = MQLs + begin-checkout, COMMITMENT = meetings/proposals + customer-data + checkout-done, DECISION = CRM wins + paid orders (or ad sale conversions when the decision stage is configured on an ads channel and no store is connected: with a store, its paid orders win, V4MOS-2863). The same person can be counted many times, and stages sum across connected tools.
  • scale separates the media-volume stages (EXPOSURE, ATTENTION) from the customer-side stages. The step BETWEEN the two groups is not a conversion rate and must be labelled as such in the UI.
  • The human-readable stage label of the bowtie (Exposição, Atenção, ...) is NOT forwarded; only stageId is returned.
  • Percentages are recomputed here AFTER filtering the configured stages — the bowtie's own percentage is ignored.

With the gtmMotionId of a motion other than the organization's default (V4MOS-2707), the stages are those of that motion's own win-flow configuration and every source is cut to the motion's connections, as GET /v1/bottleneck/funnel?gtmMotionId= documents.

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

Funnel returned successfully

application/json
  1. response
stages*array<>

Only the stages the organization configured, ordered by stageOrder. Empty when no funnel stage was configured or when no stage could be measured.

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

{  "stages": [    {      "stageId": "EXPOSURE",      "stageOrder": 1,      "count": 1250000,      "pctOfFirst": 100,      "pctOfPrevious": 100,      "previousCount": 1250000,      "scale": "media",      "source": {        "tools": [          "META_ADS",          "GOOGLE_ADS"        ],        "fields": [          "impressions",          "impressions"        ],        "resolution": "sum",        "label": "Meta Ads · Impressões + Google Ads · Impressões"      },      "frequency": 3.33    },    {      "stageId": "ATTENTION",      "stageOrder": 2,      "count": 18750,      "pctOfFirst": 1.5,      "pctOfPrevious": 1.5,      "previousCount": 1250000,      "scale": "media",      "source": {        "tools": [          "GA4"        ],        "fields": [          "session_start"        ],        "resolution": "single",        "label": "GA4 · Sessões"      }    },    {      "stageId": "QUALIFICATION",      "stageOrder": 4,      "count": 2100,      "pctOfFirst": 0.17,      "pctOfPrevious": 11.2,      "previousCount": 18750,      "scale": "customer",      "source": {        "tools": [          "GA4"        ],        "fields": [          "begin_checkout"        ],        "resolution": "single",        "label": "GA4 · Initiate checkout"      }    },    {      "stageId": "DECISION",      "stageOrder": 6,      "count": 420,      "pctOfFirst": 0.03,      "pctOfPrevious": 20,      "previousCount": 2100,      "scale": "customer",      "source": {        "tools": [          "VTEX"        ],        "fields": [          "orders_paid"        ],        "resolution": "single",        "label": "VTEX · Pedido pago"      }    },    {      "stageId": "RETENTION",      "stageOrder": 7,      "count": 63,      "pctOfFirst": 0.01,      "pctOfPrevious": 15,      "previousCount": 420,      "scale": "customer",      "source": {        "tools": [          "VTEX"        ],        "fields": [          "repurchase"        ],        "resolution": "single",        "label": "VTEX · Recompra"      }    }  ]}