Skip to main content

​
Linked Audiences

Segments and computed traits filter over a contact’s own profile — flattened attributes, events, and scores. Linked Audiences add the relational dimension: you model the entities in your warehouse (accounts, opportunities, products) and the relationships between them once, then build audiences that traverse those relationships from the unified profile. “Profiles linked to an account on the enterprise plan with at least one won opportunity” is a point-and-click audience, not a SQL query. The feature lives under Audience → Linked audiences in the dashboard, with two tabs: Audiences (the builder and list) and Data graph (the entity-relationship model). Both map to the CDP API, so everything below is also scriptable.

​
1. Model the Data Graph

The Data Graph is a per-organization metadata layer that describes what exists beyond the flattened profile. It holds definitions, not data — no SQL runs against it, and declaring an entity does not copy any rows. An entity is a warehouse table you have brought into Orbit via reverse ETL: accounts, opportunities, products, subscriptions. Each entity declares a key (its identifier), a source (the table it materializes from), a primary_key (the column relationships join on), and its traits — the columns a Linked Audience may filter on, each typed string, number, boolean, or date. A relationship connects two entities, or an entity to the unified profile, through a pair of join keys. There is one reserved entity key: profile is the implicit root every audience traverses outward from — you never declare it as an entity. A relationship also records a cardinality (one_to_one, one_to_many, many_to_one, many_to_many) so the builder and the compile step know what shape to expect. In the dashboard, open Audience → Linked audiences → Data graph and add your entities and relationships. From the API, the graph is one document you replace wholesale:
The graph is checked for referential integrity on every write: every relationship endpoint must resolve to a declared entity or the profile root, and every key must be unique. A structurally broken graph is rejected with 400 INVALID_DATA_GRAPH listing every problem at once, so fix-forward is one pass, not a back-and-forth. Keep the graph small and honest: one entity per warehouse concept, one relationship per real join, and traits only for columns you actually segment on. An audience can only filter on declared traits — if a filter you want is missing, add the trait to the entity rather than working around it in the query.

​
2. Compose a Linked Audience

A Linked Audience query roots at the profile and walks the graph. Each condition traverses one relationship and says four things:
  • via — the relationship key to traverse. Relationships are walkable from either endpoint, so the side you happened to enter as from when declaring the graph never limits the builder.
  • where — filters over the target entity’s declared traits, ANDed together. Operators match the trait type: numeric (gt, between, …), string (contains, in, …), boolean, date (within_days, after, …), plus exists / not_exists on any type.
  • quantifier — how many related rows must match: exists (default), none, at_least, or at_most (the last two take a count). “Profiles with no open opportunities” is an audience you can build in one step.
  • and — optional nested conditions that continue the walk from the entity this step landed on. Profile → account → opportunity is a nested traversal, and profiles are matched only when every hop resolves.
Top-level conditions combine with all (AND) or any (OR). Define the audience from the Audiences tab by clicking Create audience, or create it over the API:
The response carries the saved audience with its id. Names must be unique per organization — a duplicate name is a 409, and a query that does not resolve against the current graph is a 400 INVALID_LINKED_AUDIENCE with the offending paths spelled out.

​
3. Preview with validate and compile

Checking a draft costs nothing — two endpoints evaluate a query without persisting it. POST /api/v1/cdp/linked-audiences/validate resolves a query against the current graph and returns valid, the full issues list ({ path, message } pairs, all of them at once), and — when it validates — the compiled plan:
The compiled plan is the builder’s “explain” view: the traversal steps resolved against the graph plus a one-paragraph human-readable summary — for the example above, “Profiles related to an Account where plan_tier eq “enterprise”.” Show it in your own builder UI or read it before enabling, so a logically wrong but syntactically valid audience is caught by a human before it goes live. POST /api/v1/cdp/linked-audiences/:id/compile does the same for a stored audience. That distinction matters because the graph can move after an audience was saved: rename an entity or drop a relationship and the stored query no longer resolves. Compile returns 409 AUDIENCE_GRAPH_DRIFT with the broken paths when that happens — treat the drift report as the prompt to either repair the audience or restore the graph shape it depends on. Validation is strict in both directions: profile-trait filtering (lifecycle stage, tags, scores, events) belongs in segments and computed traits, not inside a relational step, so a where clause walking back to the profile root is rejected. Compose the two — a saved segment supplies the profile-trait half, a linked audience supplies the relational half.

​
4. Publish to destinations

An enabled Linked Audience is a saved membership definition; how it is consumed mirrors every other audience surface. The usual downstream destinations:
  • Ad networks. Map the audience to a destination audience on Meta, Google, TikTok, LinkedIn, Snapchat, Pinterest, Reddit, The Trade Desk, or Criteo and sync membership — identifiers are normalized and hashed before dispatch. The activation flow is the same one documented in step 6 of the CDP audiences guide.
  • Campaigns and flows. An enabled audience can feed a campaign or enroll-on-entry flow, so relational targeting (“accounts with an open opportunity”) drives a send the moment membership resolves.
  • Warehouse. Sync the audience back to your warehouse via reverse ETL alongside your other audience exports, where it joins back to the entities it was built from.
The enabled switch on the audience row (or PATCH /api/v1/cdp/linked-audiences/:id with { "enabled": false }) pauses materialization without deleting the definition — the graph, the query, and the destinations stay configured and the audience can be re-enabled later. Deletes are permanent: the definition is removed and no longer materialized.

​
5. Roles and audit

Managing the graph and audiences requires the owner, admin, or developer role. Analysts and marketers can read and validate, which is what lets the builder preview a draft without granting write access. Every graph replacement and every audience create, update, and delete is written to the audit log, so a changed audience definition is always attributable.

​
6. Recipes

​
At-risk profiles on enterprise accounts

Retention outreach aimed where the revenue is — profiles on enterprise-tier accounts, further narrowed by churn risk in a composed segment:
Combine the linked audience with a churn_risk > 0.6 segment from the CDP audiences guide as your campaign’s target.

​
Dormant product, active purchasers

Profiles linked to accounts that purchased a product — then suppress the purchasers of the flagship SKU from the promo with a none quantifier:

​
Renewal window

Profiles on accounts with at least one subscription closing inside the next 90 days — the within_days operator evaluates relative windows without timestamp math:

​
See also