Find the constraint in the paid funnel

Target server for requests. Edit to use your own host.

Location to scope to. Required for ak_ keys (or send the X-Location-Id header); ignored for sk_.

Window start (YYYY-MM-DD). Defaults to 28 days before to.

Window end (YYYY-MM-DD), inclusive. Defaults to yesterday.

Window length in days, inclusive of both ends — the same shorthand /client/v1/data takes. days=90 ending yesterday is the usual call. Ignored when from is given explicitly. Out-of-range values are rejected, not clamped.

Grain of the analysis. ad is where creative lives, but it matches through utm_content, which carries a usable ad identifier on far fewer accounts than utm_id does — expect a lower match_rate.

session uses the conversion's own session's campaign when it has one, else the person's MOST RECENT paid touch in the window — effectively last-paid-touch, closest to what the ad platform itself would claim. first_touch uses the person's EARLIEST paid touch: the campaign that first acquired them, however long ago.

Event name counted as the conversion. Discover this client's real event names via GET /client/v1/data/events/breakdown?dimension=event_name. Pass `auto` to let the endpoint choose: it runs the eligibility probe first, takes its suggested pairing, and reports the choice under auto_selected so it is visible rather than magic. That replaces a round trip you would otherwise make to /constraints/events purely to learn which event to ask about. An explicit lead_event still wins over the suggestion. If nothing in the window can serve as a conversion you get a 422 no_usable_conversion_event rather than an analysis of a dead funnel.

Optional mid-funnel event. Supplying it splits the on-site step into landing and sales. Must differ from conversion_event.

Rows below this many impressions are excluded from the analysis but still counted in the pooled benchmarks — dropping them from the pool would inflate the bar the surviving rows are judged against.

Drill into one campaign, matched by campaign id or name (trimmed, case-insensitive). With group_by=adset or ad it scopes the rows to that campaign's children. Benchmarks stay the account-wide pooled rates, so the campaign is still judged against the whole account — that comparison is the point of the drilldown. If nothing matches, the response carries a campaign_not_found diagnostic instead of a silent empty list.

Return only one Meta ad account's rows: the numeric id, with or without the act_ prefix Ads Manager shows (act_1234567890 and 1234567890 are the same filter). Anything else is a 400. The filter runs after attribution. Conversions are credited across every ad account in the location first, then the rows are filtered, so a person who clicked an ad in account A and later one in account B is credited once, to whichever touch the attribution model picks, and never to both accounts. Benchmarks, pooled_rates, tracking, conversion_attribution and any diagnostic stay location-wide; the response says so with diagnostics_scope: location and adds account_totals. Combine with campaign to narrow further. If the account has no rows in the window the response carries an account_not_found diagnostic.

Ad platform. Only meta is supported; google answers 501 platform_not_supported until a Google Ads adapter exists.

JSON path to the conversion's monetary value inside the event's properties. properties_json is the properties object, so the path is $.value, not $.properties.value. Pass none when the conversion event carries no value (the /constraints/events inventory lists each event's revenue_paths). Revenue is then not read at all: revenue is 0, roas is null and revenue_measured is false. Reading the properties is most of the scan on a small client (measured: 4.2 of 7.1 GB), so this makes the call cheaper and faster. conversion_event=auto does this by itself when the event it picks has no value path.

Meta insights table in the client's dataset, if it differs from the platform default.

How long after a campaign touch a conversion may still be credited to it. A conversion with no session of its own (all CRM/server-side conversions) is credited to the person's nearest campaign touch inside this window; touches are looked up back to from minus the window, so early-window conversions still find the visit that earned them. Meta's own default is 7-day click — pass 7 for numbers comparable to Ads Manager. Pass 0 for strict own-session credit only (disables person crediting; the conservative reading).

Comma-separated optional sections, all off by default: include=creative,audit,events,placements. creative adds each row's ad copy, destination and assets. Off by default because it is not free: measured on one client it scans 285.9 MB on every call at every grain, independent of the report window (the creatives table sits in a single partition that nothing prunes, and one JSON column is 139 MB of it). If you join creative yourself, leave it off. Row labels are unaffected — ad_name comes from ads-insights and top_landing_page from sessions. audit returns the tracking-hygiene report (the same body as /constraints/audit) under an audit key, and events returns the event inventory (/constraints/events) under event_inventory. These stay separate BigQuery jobs — one request cannot make them one scan — but they run in parallel with the analysis, so a caller that needed all three stops paying three serial round trips and pays the slowest one instead. placements splits every row by Meta placement (facebook, instagram, audience_network, messenger, threads) with spend, impressions, link clicks, Meta landing page views and Meta leads, and rolls the account up by placement under a top-level placements. Audience Network behaves unlike the rest (measured on one account: 71% of clicks, a 37% click rate, no leads), and summed into a row it reads as a healthy ad with a weak page. Needs the ads_insights_delivery_platform stream on the Meta connection; without it the section is {"unavailable": "stream_not_synced"}. A section that fails is reported as {"unavailable": "<reason>"} inside a 200; the analysis itself is never failed by it. An unknown name is a 400 rather than a silent omission.

IANA time zone the funnel's days are bucketed in, e.g. America/Los_Angeles. Meta reports in the ad account's time zone (its date_start is that account's local day), so our events are moved onto the same calendar; left to UTC, a Pacific account's evening clicks land on the next day on one side only (measured: a day of 13 clicks read as 22 in UTC). Default: the location's stored time zone, else UTC. The response states the zone used in window.timezone and where it came from in window.timezone_source. Also sets the default to (yesterday in that zone). An unknown name is a 400.

Identity stitching — resolve people through the central identity snapshots (merge tombstones collapsed) rather than the raw distinct_id. On by default, and you almost never want it off. A CRM/server-side conversion arrives with no session of its own, so credit can only reach a campaign through the person; the conversion's distinct_id is a CRM contact id that shares nothing with the browsing device's id until the snapshot maps both onto one person. Measured on one client over 30 days (273 conversions): the raw distinct_id could credit 10% of conversions to a paid touch, canonical persons credited 81%. Pass false (or 0) to opt out — useful only to reproduce a figure from before this was the default. conversion_attribution.identity_resolution reports how much of the resolution actually worked.

Target rate for the impressions -> clicks step, replacing the account's pooled rate. A rate between 0 and 1 — a 2% CTR target is 0.02. Values above 1 are rejected, not interpreted as percentages.

Target rate for the clicks -> sessions step. Rate between 0 and 1.

Target rate for the sessions -> leads step. Rate between 0 and 1. Requires lead_event; without it this step does not exist and the request is rejected.

Target rate for the leads -> conversions step. Rate between 0 and 1. Requires lead_event.

Target rate for the combined sessions -> conversions step. Rate between 0 and 1. Only valid WITHOUT lead_event, which splits this step into landing and sales.