Infinite Audience MCP Server

Preview the count for one requested population; this does not create a saved audience. With segment_id, the current segment count snapshot is updated. Returns count and optional group_by breakdown. Use filters (AND conditions) or filter_groups (advanced compound filters), segment_id (resolve filters from a saved segment), audience_id (resolve from a saved audience), or segment_ids+set_logic (compose multiple segments, optionally with excluded_segment_ids for an ad-hoc "A minus B" preview). All inputs are mutually exclusive — providing more than one is rejected with AMBIGUOUS_INPUT. Requires 'discovery' scope.

Generate a cross-tabulation pivot table across two demographic dimensions. Returns rows, columns, bounded cells, total_count for the full population, displayed_count for visible cells, and truncated when row/column limits omit categories. Accepts EXACTLY ONE of: filters (flat array), filter_groups, segment_id, audience_id, or segment_ids+set_logic to define the audience population (more than one is rejected with AMBIGUOUS_INPUT). Grouped logic, saved audience exclusions, and record limits are preserved. Requires 'discovery' scope.

Return up to 25 masked sample rows for audience matching criteria. Accepts: filters (raw Filter objects), segment_id, audience_id, segment_ids+set_logic (optionally with excluded_segment_ids for an ad-hoc "A minus B" preview), or filter_groups. All inputs are mutually exclusive — providing more than one is rejected with AMBIGUOUS_INPUT. Saved compositions and their exclusions are preserved. Requires 'discovery' scope.

Calculate the overlap between two audience criteria sets. Returns overlap_count, overlap_pct (percentage of the smaller population), and demographic_deltas. Each side (a and b) independently accepts EXACTLY ONE of: audience_id, segment_id, segment_ids+set_logic, filter_groups, or filters (more than one per side is rejected with AMBIGUOUS_INPUT). Saved composition, exclusions, and record limits are preserved. Empty optional distributions mean unavailable, not zero. Legacy: pass audience_id_a and audience_id_b at the top level for backward compatibility (mutually exclusive with a/b). Requires 'discovery' scope.

Create a segment of the specified subtype. Segments are the typed cohort definitions — audiences are composition wrappers built from segments. filter: reusable filter definition — returns immediately with status active and an unset count unless count_snapshot is supplied. Call count_segment to calculate its saved count. matched: upload a file — returns upload_url (30-min presigned), or upload_urls (an array, one per shard) when shard_count > 1. The upload is staged (not resolved automatically): PUT the raw file bytes to each returned URL with Content-Type matching file_format: csv=text/csv, avro=application/avro, json=application/json, jsonl=application/x-ndjson. Do not include the MCP bearer token in this upload. After uploading (all shards, if multiple), call analyze_audience_upload(segment_id) (analyzes the first shard only when sharded — all shards must share one schema), present the mappings to the user and wait for their response, then confirm_column_mappings(segment_id) to start resolution (or cancel_matched_upload(segment_id) if they decline) — only THEN call wait_for_segment(segment_id). Subscription capacity for file matching is consumed with the first successful delivery, together with the delivery capacity. Custom segments are published through the internal data-team tool; this customer tool creates filter or matched segments only. Use file_format to specify csv (default), avro, json, or jsonl and compression=gzip for gzip bytes. Set shard_count > 1 for multiple same-format files; all shards must use the same compression and every CSV shard must include its own header row. Set create_audience=true to automatically wrap the new segment in an audience for immediate delivery. Optional campaign_id records the campaign the segment is built for and links that wrapper audience to it; omit it to leave both outside any campaign. Async build completion or failure may notify configured external webhooks and opted-in users by email. Requires 'creator' scope.

Fetch one segment by segment_id. Returns its customer-facing subtype, status, count, and subtype-specific fields. Filter segments include the complete filter_groups definition and current_version; matched and model-generated segments expose their own relevant fields. An expired segment may have its stored status synchronized to expired during this read; no build or count is started. Requires 'discovery' scope.

List every audience that references a segment, with campaign linkage. Returns audiences[] ({id, name, campaign_id, status, record_count}), audience_count, and campaign_count. Use before archiving, refreshing, or editing a segment to understand downstream impact, or when the user asks where a segment is used across campaigns. Requires 'discovery' scope.

Profile one saved segment on its own, without any audience set logic or exclusions. Returns a BigQuery-computed demographic breakdown (age buckets, geography, and a behavioral/financial extra when available) evaluated directly over the segment's own definition — the segment-level path, with no audience composition (set_logic/exclusions) applied. Works for any subtype (filter, matched, custom) — non-filter subtypes resolve via the same underlying ID-set composition audiences use. Results may populate a 20-minute server-side cache and record query telemetry; the segment definition is unchanged. Requires 'discovery' scope.

Create an audience from one or more existing segments. Audiences are the delivery payload — they have no subtype. To create filter or matched cohorts, use create_segment instead. Accepts segment_refs: [{segment_id, role: include|exclude}] to compose the audience with per-segment inclusion/exclusion control. set_logic controls how include-role segments are combined (union or intersection). Returns audience_id, status and campaign_id immediately. Use record_count only for a verified count of this exact composition. Optional campaign_id links the new audience to that campaign (an audience belongs to at most one); omit it to leave the audience unlinked — link it later with link_audience_to_campaign. Requires 'creator' scope.

Get customer-facing details of an audience, including expanded segment summaries and composition. Use when the user wants to inspect a specific saved audience. An expired audience may have its stored status synchronized to expired during this read; no build or count is started. Requires 'discovery' scope.

Profile a saved audience composition, including its segment set logic and exclusions. Returns a BigQuery-computed demographic breakdown, including median age, gender split, homeowner %, children %, college-educated %, and high-income %. Results may populate a 20-minute server-side cache and record query telemetry; the audience definition is unchanged. Requires 'discovery' scope.

Create a new campaign workspace with an optional brief and goals. Use when the user wants to start a new initiative, project, or campaign. Returns the new campaign object including its id. Requires 'creator' scope.

Retrieve customer-facing details for a campaign including its brief and linked audience summaries. Use when the user asks about a specific campaign or wants to see what audiences are in it. Linked segments are summaries; call get_segment with a segment ID to inspect its filter_groups definition. Requires 'discovery' scope.

Update a campaign name, description, or status. Set status=archived to soft-archive it while preserving linked audiences; set status=active to restore an archived campaign. Requires 'creator' scope.

Retrieve a single file-based identity resolution job by its match_id (= segment_id). Returns full details including matching_status, file_format, compression, field_counts, source_job_id, audience_id, audience_status, and error_message if failed. Matching capacity consumption is reported after the first successful delivery. Its monetary estimate is denominated in USD and covers the matching component separately from delivery. audience_status (active/archived/null) reports whether the linked audience is still open-able in Library. mapping_warnings lists problems with how the file's columns were used (code nested_addresses means the addresses column was ignored in whole or part) — tell the user about any entries. Use to check job progress after create_segment(subtype=matched), or to retrieve the audience_id for delivery. Requires 'discovery' scope.

List deliveries for a file-based identity match job, including status and delivery IDs. Signed download links are omitted from history; call get_delivery for a specific completed delivery. Requires 'discovery' scope.

List async file-based identity resolution jobs for the org. Each job corresponds to a matched segment created via create_segment(subtype=matched). Returns match_id, name, status, matching_status, input_record_count, match_count, match_rate, file_format, compression, segment_id, audience_id, audience_status, created_at, expires_at. Matching capacity consumption is reported after the first successful delivery. Its monetary estimate is denominated in USD and covers the matching component separately from delivery. audience_status (active/archived/null) reports whether the linked audience is still open-able in Library — job history itself always persists, even after the segment or audience is deleted. Cursor-paginated. Filter by status to find pending/active/failed jobs. Requires 'discovery' scope.

Retrieve a single micro-batch match run by its run_id. Returns full details: match_count, match_rate, input_record_count, estimated subscription capacity consumption in USD, field_list, status, created_at, expires_at. Requires 'discovery' scope.

List past micro-batch identity match calls for the org. Returns run_id, match_count, match_rate, field_list, created_at, and expires_at. Results are cursor-paginated — pass next_cursor as cursor to fetch older pages. The before timestamp is a legacy alternative. Reported subscription capacity consumption is an estimate in USD; final rated consumption may differ. Use to audit recent match activity, inspect subscription capacity consumption, or find a specific run by scanning pages. Requires 'discovery' scope.

Perform real-time identity resolution on up to 100 records. Returns run_id, match_count, record_count, match_rate, and records[] — one output record per input record, matched or not (each with row_id, iag_person_id, match_level, match_type, match_confidence, enrichment fields, and the licensing labels below). iag_person_id is an org-scoped, non-reversible id: present on a real match, or a best-effort id derived from the row's own identity signals (or null) when unmatched — use match_count/record_count, not id-presence, to tell real matches from derived-only rows. Each record also carries resolution_action (resolved = organic PII match, refreshed = the row submitted a valid iag_person_id, unmatched = no real match, identity_unavailable = a previously valid id no longer resolves to deliverable data) and license_action (none, started, or renewed), plus license_expires_at (ISO-8601 or null) — these two fields are independent: a row can be resolution_action "resolved" and license_action "renewed" at once. The run_id can be passed immediately to get_match_run to retrieve or audit this call later. Matching consumes subscription capacity for real matches. Returned monetary consumption values are estimates in USD; final rated consumption may differ. A tier-01 Person ID from a prior real match or licensed audience delivery can go directly to Refresh; an audience-only ID has null match_level until a real match occurs. Include I in match_level for direct ID lookup, or omit the filter. Active identity licenses provide existing coverage for the identity component. For more than 100 records, use create_segment(subtype="matched") with a file upload instead. A subscription-capacity refusal may notify configured external webhooks. Requires 'creator' scope.

Archive a saved audience to hide it from the default list, or restore it with restore=true. Preserves its composition and delivery history. Requires the creator scope. Requires 'creator' scope.

Archive a segment to hide it from the default segment catalog and new audience compositions, or restore an archived one back to active. Archiving changes where the segment can be used; restoring it is a separate action. Archiving does not affect audiences that already reference this segment — their composition and record count are unchanged. This is distinct from permanently deleting a segment, which does change referencing audiences' composition and cannot be undone. Requires the creator scope. Requires 'creator' scope.

Deliver an audience as a download using available organization subscription capacity. Required capacity depends on the selected records, attributes, and existing licenses. Supply template_id OR field_list — not both. Review the subscription capacity estimate from quote_delivery with the user before starting delivery. Returns delivery progress and signed download links once completed. Completion or failure may notify configured external webhooks and opted-in users by email; completion may also email the delivery creator and configured organization contacts. Requires 'creator' scope.

Trigger download delivery for a file-based identity match job. Always delivers to download — returns a signed URL to the enriched output file. Use this instead of deliver_audience for matched segments created via create_segment(subtype=matched). The match_id is the segment_id returned by create_segment(subtype=matched) — delivery still routes through an audience wrapper internally. Matched segments do not support LiveRamp or Narrative destinations. Supply template_id OR field_list — not both. Use get_field_catalog() to browse options. Completion or failure may notify configured external webhooks and opted-in users by email; completion may also email the delivery creator and configured organization contacts. Requires 'creator' scope.

Create a duplicate of an existing audience with lineage tracking (parent_audience_id + derived_from root ancestor, segment versions pinned at duplicate time). The duplicate carries the source composition (segment_ids, excluded_segment_ids, set_logic), is immediately active, and starts with record_count null — call recount_audience for a fresh count. Optionally link the duplicate to a campaign. Requires 'creator' scope.

Create a duplicate of an existing segment. Preserves the source subtype and all subtype-specific data: filter criteria for filter segments; match results, column mappings, and match counts for matched segments; immutable membership version and expiry for custom segments (underlying computed data is referenced, never recomputed). Lineage is recorded (parent_segment_id, derived_from root ancestor, parent_segment_version pin). Filter duplicates start with record_count null — trigger a recount with count_segment for a fresh count; matched/custom duplicates carry the source's counts. Returns 409 SOURCE_MATCH_UNAVAILABLE when a matched source's match data is unavailable (expired/failed/incomplete match), or 409 SOURCE_NOT_READY when a non-matched source is pending or failed. Requires 'creator' scope.

Get one retained integration run by run_id. Returns customer-safe provenance, selected fields, record counts, processing status, and subscription capacity source; intermediate workflow artifacts are not exposed. Use an ID from list_integration_runs. Requires 'discovery' scope.

List safe, retained integration activity for this organization. Intermediate workflow artifacts stay private, while this projection records provenance, counts, selected fields, and subscription capacity source. Results are cursor-paginated. Supply at most one of provider, connection_id, kind, or status; use next_cursor to continue. Requires 'discovery' scope.

Edit name, description or labels, archive/restore, or change the composition of an existing audience. Also supports adding/removing included or excluded segments. set_logic must be "union" or "intersection" — never "exclusion". To exclude records, use add_excluded_segment_id. Requires 'creator' scope.

Edit segment name, description or labels, or replace a filter segment definition. Supply filters OR filter_groups, never both. record_limit=null removes a size limit; a positive limit requires bounded State, City, or ZIP Code geography. Definition changes create a new version; renaming does not. Use archive_segment to archive or restore. Requires the creator scope. Requires 'creator' scope.

Refresh one named member segment of an audience against the current IAG, then refresh the audience's own version/expiry. An audience is a composition of one or more member segments, possibly of different subtypes — there is no "primary" segment, so segment_id is required (400 SEGMENT_ID_REQUIRED if omitted, 400 SEGMENT_NOT_A_MEMBER if it is not part of this audience). Behaviour is specific to the chosen segment's subtype: - filter: synchronous — returns status: active immediately. record_count is null; call recount_audience if a fresh count is needed before quoting. - matched: with hitl false/unset (default): returns status: pending + upload_url. Instruct the user to upload their identity list to upload_url (same or updated file). After upload, call wait_for_segment(segment_id) to block until identity resolution completes. With hitl: true: the upload is staged instead — follow the analyze_audience_upload -> confirm_column_mappings / cancel_matched_upload -> wait_for_segment sequence documented on create_segment(subtype=matched) (confirm_column_mappings/cancel_matched_upload take this segment_id, not audience_id). - custom: immutable snapshot; returns 409 CUSTOM_REGENERATION_REQUIRED. Request a new internal data-team publication. Always call get_audience first to see the member segments and their subtypes, so you can pick (or have the user pick) the right segment_id. Async build completion or failure may notify configured external webhooks and opted-in users by email. Requires 'creator' scope.

Re-derive a single stale or expired segment from the current IAG. Updates ONLY the segment — referencing audiences are never touched; the response lists them in affected_audiences so you can recount or refresh them (use refresh_audience for a whole-composition refresh). Behaviour is subtype-specific: - filter: synchronous — bumps current_version, nulls record_count, resets the 90-day TTL, returns status: active. If the segment is already fresh the call is a no-op (refreshed: false); pass force: true to bump anyway. Call count_segment afterwards for a fresh count. - matched: with hitl false/unset (default): returns status: pending + upload_url (24 h presign) targeting the canonical upload path — or upload_urls (an array) when shard_count > 1 — instruct the user to re-upload their identity list (one same-format file per URL for a sharded upload; every CSV shard needs its own header); identity resolution runs automatically once all shards are uploaded. Then call wait_for_segment(segment_id). With hitl: true: the upload is staged instead — after upload, follow the analyze_audience_upload -> confirm_column_mappings / cancel_matched_upload -> wait_for_segment sequence documented on create_segment(subtype=matched). Returns 409 SHARED_SOURCE_DATA for matched duplicates that reference another segment's data — the message names the source segment to refresh instead. - custom: immutable snapshot; returns 409 CUSTOM_REGENERATION_REQUIRED. Request a new internal data-team publication. Returns 409 SEGMENT_ARCHIVED for archived segments — restore them first with archive_segment(restore=true). Async build completion or failure may notify configured external webhooks and opted-in users by email. Requires 'creator' scope.

Check a saved-match segment materialization by materialization_id after build_saved_integration_segment. Returns aggregate progress/status and the durable segment ID once complete; it does not start another build. Requires 'discovery' scope.

List saved integration matches available to build into a segment. Returns aggregate counts, refreshes stored collection counts, and may initialize collection metadata. Use preview_saved_integration_segment before building. Requires 'discovery' scope.

Block until a delivery completes or fails. Call this immediately after deliver_audience or deliver_file_match when the response has status: "processing". Polls GET /v1/audiences/{audience_id}/deliveries/{delivery_id} every 15 seconds. On success returns the full delivery object including download_urls[] — share these directly with the user. Each signed link is valid for 24 hours; expires_at is the delivery artifact retention date, not the link expiry. Call get_delivery for a fresh link while the artifact remains available. Throws DELIVERY_FAILED if the export failed (check failure_reason), or DELIVERY_TIMEOUT if it did not finish within timeout_seconds (default 30 seconds). A wait timeout does not cancel or fail the job; use the corresponding get tool to check it again. Requires 'discovery' scope.

Poll a segment until its status is "active" or "failed". Use after create_segment(subtype=matched) once the file has been uploaded AND confirm_column_mappings has succeeded — the segment will not progress past "pending" before that (the upload is staged). Do not call this before confirm_column_mappings. Custom membership is published internally; use this tool to read a pending segment publication. Polls GET /v1/segments/{segment_id} every 15 seconds; polling may synchronize an expired status onto the saved segment. On success returns the customer-facing segment details — pass segment_id in create_audience.segment_refs, then use the returned audience_id to quote_delivery and deliver_audience. Throws SEGMENT_FAILED if processing failed, or SEGMENT_TIMEOUT if it did not complete within timeout_seconds (default 30 seconds). A wait timeout does not cancel or fail the job; use the corresponding get tool to check it again. Requires 'discovery' scope.

Read organization totals, recent delivery activity, subscription capacity consumed in the current period, capacity snapshot freshness, and compute utilization. Monetary capacity values use cents. Requires 'account-read' scope.

Search org delivery history across audiences with pagination. Supports status, destination, and audience_id filters, Use audience_id to narrow the search to one audience, or list_deliveries for its latest 100 deliveries. Signed download links are omitted; call get_delivery for one completed artifact. Requires 'discovery' scope.

After uploading a file to the presigned upload_url (or all same-format shards to upload_urls) returned by create_segment(subtype=matched), call this to run LLM-assisted column mapping inference. For a sharded upload, analysis runs against the first shard only — every shard is assumed to share the same schema; a mismatch fails the batch job later with a specific error, not silently here. Returns: segment_id, analysis.columns[] (each: source_column, mapped_to, inferred_type, confidence 0–1, warning), analysis.unmapped_columns[] (column headers that could not be mapped), analysis.recommendations[] (human-readable tips to improve match rates). gzip is detected from file bytes, so a missing or incorrect compression declaration is self-healed during analysis. Returns typed 422 errors for malformed gzip, format mismatch, or malformed input, and 409 FILE_NOT_YET_UPLOADED before upload. The upload is staged (create_segment sets hitl:true) — nothing has started yet. Present these results to the user and wait for their response, then call confirm_column_mappings (to start resolution) or cancel_matched_upload (to abort) — do not call wait_for_segment before confirm_column_mappings succeeds. Requires 'discovery' scope.

List a page of non-archived saved audiences for this organization, including status, saved count and campaign_id (null when the audience is in no campaign). Use to find an audience_id before get_audience, recount_audience, or delivery; pass a limit of 1–100. Pass campaign_id to list one campaign's audiences, or unlinked=true for audiences in no campaign (not both). A filtered page can hold fewer than limit audiences — keep following next_cursor until it is null. Requires 'discovery' scope.

Read the organization subscription capacity, reserved and pending consumption, replenishment status, and snapshot freshness. For an agency-managed organization, the response describes its attributed subscription consumption. Requires 'account-read' scope.

Create a matched segment, or add unique saved identities to a compatible standalone matched segment. Call preview_saved_integration_segment first and confirm the exact counts and target with the user. Adding to an existing segment replaces its current version. Completion or failure may notify configured external webhooks and opted-in users by email. Reuses previously resolved identities and returns a segment for subsequent audience composition. Requires 'creator' scope.

List a page of campaigns for the organisation. Use when the user asks "what campaigns do I have?" or "show my active campaigns". Returns each campaign brief and status; use get_campaign for linked audience details. Pass the returned next_cursor as cursor to fetch another page. Requires 'discovery' scope.

Abort a staged matched-segment upload without confirming. Call this when the user declines to proceed after reviewing analyze_audience_upload's results. Clears the staged upload — no file move, no status/mapping-state change. The existing segment is retained; cancellation does not delete it or complete matching. Inspect it with get_segment and archive it with archive_segment if no longer needed. Idempotent. Pass exactly one of segment_id or audience_id — use audience_id when only the audience is known (it resolves to that audience's matched member segment server-side). Requires 'creator' scope.

Confirm column mappings for a staged matched-segment upload, starting identity resolution. Call this after analyze_audience_upload has been reviewed with the user and they approve (with or without edits). This moves the staged file into place — nothing runs before this call succeeds. Only call wait_for_segment after this returns ok. Pass exactly one of segment_id or audience_id — use audience_id when only the audience is known (it resolves to that audience's matched member segment server-side). When using audience_id, column_mappings is required (no auto-inference fallback on that path). When using segment_id, column_mappings may be omitted — the platform re-analyzes the active upload itself and accepts its own suggested mapping as-is. Async build completion or failure may notify configured external webhooks and opted-in users by email. Requires 'creator' scope.

Refresh the stored record_count of one saved segment, not its parent audience. Runs a fresh BigQuery count over the segment's own definition for any subtype (filter, matched, custom), updates segment.record_count. Returns {segment_id, record_count}. For an unsaved population preview use discovery_count; for a composed audience snapshot use recount_audience. Requires 'discovery' scope.

Read the current platform data-release version (current_release_major/minor) and snapshot timestamp. Does not refresh the registry or change saved data. Returns DATA_RELEASE_UNAVAILABLE if the registry is not populated yet. Requires 'discovery' scope.

List up to 100 deliveries for one accessible saved audience. This audience-scoped path checks the audience and its member segments before returning history. Signed download links are omitted; call get_delivery for one completed artifact. Use list_all_deliveries for an org-wide paginated search. Requires 'discovery' scope.

Get status and details of a single delivery. Returns fresh 24-hour download_urls[] for completed download deliveries while the artifact is retained; expires_at is the artifact retention date, not the signed-link expiry. Use this to poll status after deliver_audience returns status: processing. Requires 'discovery' scope.

Discover a bounded page of fields, descriptions, accepted aliases, allowed filter operators, coded values and coverage definitions. Search zip or zip_code for the canonical zip5 field. State publishes two-letter codes and full-name labels; either input is accepted. Defaults to filterable audience fields; use purpose=enrichment for all output fields. feature_store fields are enrichment-only unless also tagged audience. Follow next_cursor for more fields; for more enum values pass field_name and values_next_cursor as value_cursor. Subscription capacity rates are opt-in. Requires discovery scope. Requires 'discovery' scope.

Link an existing audience to a campaign. Each audience can belong to at most one campaign. This is idempotent — calling it again for an already-linked pair is safe. Fails with AUDIENCE_ALREADY_LINKED (naming current_campaign_id) if the audience is already in a different campaign — unlink it there first. Requires 'creator' scope.

Preview exact unique identities, duplicate receipts, expiry/privacy exclusions, existing overlap, and net additions before creating or extending a segment. Returns an estimate for review before materialization. Requires 'discovery' scope.

Estimate the subscription capacity required for a download using the audience version, selected fields, output settings, and current licenses. Saves a pending estimate and updates the audience estimate reference. Returns an expected amount and an upper bound, denominated in USD, together with available-capacity sufficiency and any shortfall. Active licenses reduce the expected identity component. When license information is unavailable, the expected amount equals the upper bound. The matching component for a file upload is included when applicable. Review the expected amount and upper bound with the user before delivery. Requires 'discovery' scope.

Refresh the stored record_count of one saved audience from its current included/excluded segment composition. Call after adding or removing segments. For an unsaved population preview use discovery_count; for a segment snapshot use count_segment. Requires 'discovery' scope.

List a page of visible, non-archived saved segments with subtype, status, and record counts. Use when the user asks what segments they have; filter by subtype or pass a limit of 1–100. For one complete definition, call get_segment with its segment_id. Requires 'discovery' scope.

Read verified status for an existing subscription capacity replenishment request. Supply the request identifier from its original confirmation. Requests requiring attention are identified for an account administrator. Requires 'account-read' scope.

Remove the link between an audience and a campaign, leaving the audience itself untouched. This is idempotent — calling it again for an already-unlinked pair is safe (returns ok:true). Requires 'creator' scope.