Create LinkedIn Engagement Retargeting Audience
create_linkedin_engagement_retargeting_audienceCreate a LinkedIn Engagement Retargeting audience: people who already engaged with the advertiser's LinkedIn ads, company page, or website. STEP 3 of the flow.
This is NOT create_retargeting_audience, which imports an audience the ad account
already has. This builds a NEW LinkedIn DMP segment from the engagement rule defined
here. Once built it is a normal Metadata audience and can be attached to campaigns.
**REQUIRED WORKFLOW — do not call this tool first:**
1. get_linkedin_engagement_source_types → choose `source_platform` + `engagement_trigger`
2. For every source type EXCEPT WEBSITE: search_linkedin_engagement_sources with that
trigger and lookback → collect each chosen result's `id` into
`engagement_source_urns`
3. Call this tool
Source types, triggers and URNs are LinkedIn's own values, and only steps 1 and 2
can supply them. Do not invent, guess or reuse one from another account: a value
that did not come from those steps either fails outright or, worse, is accepted and
builds an audience that never populates.
**TWO SHAPES, MUTUALLY EXCLUSIVE — mixing them is rejected:**
A) NON-WEBSITE (VIDEO_ADS, SINGLE_IMAGE_ADS, DOCUMENT_ADS, CONVERSATION_ADS,
LEAD_GEN_FORMS, ORGANIZATION_PAGES):
pass `engagement_source_urns`. Do NOT pass page_set_name or url_match_groups.
B) WEBSITE:
pass `page_set_name` and `url_match_groups`. Do NOT pass engagement_source_urns.
Metadata creates the LinkedIn page set from those URL rules for you.
URL MATCH RULES (WEBSITE only) are a LIST OF GROUPS. Rules inside a group are ANDed;
the groups are ORed. Each rule is {matchType, matchValue}, matchType being EXACT
("URL equals"), STARTS_WITH, or CONTAINS.
[[A, B], [C]] means (A AND B) OR C
Worked example — "anyone who hit pricing or any demo page":
[[{"matchType": "STARTS_WITH", "matchValue": "https://example.com/pricing"}],
[{"matchType": "CONTAINS", "matchValue": "/demo"}]]
Use one rule per group for a simple OR list, which is what most requests mean. Reach
for a multi-rule group only for a genuine AND, e.g. a path that also carries a
campaign parameter.
WHEN TO USE:
- "Retarget everyone who watched our video ads in the last 90 days"
- "Build an audience from people who submitted the lead form"
- "Create an audience of visitors to our pricing and demo pages"
- "Retarget people who visited our LinkedIn company page"
- "Make a warm audience from last quarter's ad engagement"
PARAMETERS:
- name: audience name (required). Give it something descriptive of the rule, e.g.
"Video 50% viewers 90d", so it is recognisable in the audience list later.
- source_platform: the chosen `engagementSourceType` (required)
- engagement_trigger: a trigger listed for THAT source type (required). NOTHING
VALIDATES THE PAIRING — see the warning below.
- lookback_window_days: 30, 60, 90, 180 or 365 — WEBSITE caps at 180 (required)
- engagement_source_urns: LinkedIn URNs from search_linkedin_engagement_sources,
copied verbatim. Required for every source type except WEBSITE. Several are
normal: the audience is everyone who engaged with ANY of them.
- page_set_name: internal label for the URL rule set (WEBSITE only, required there).
Only ever seen inside LinkedIn, so a plain descriptive label is fine.
- url_match_groups: the OR-of-ANDs URL expression (WEBSITE only, required there)
RETURNS:
Confirmation with the new audience `id` and name, the `criteria` that define it
(source, trigger, lookback, how many sources), the channel, and a `note` on when it
becomes usable.
**WHAT TO TELL THE USER AFTER IT SUCCEEDS:**
It is created but not yet populated. LinkedIn takes up to 48 hours to build the
audience and a further 24 hours before it delivers, so it will show NO match count
and NO contact or company numbers immediately. That is expected and correct, not a
failure. Say so plainly rather than reporting the audience as empty or broken.
IMPORTANT NOTES:
- **THE TRIGGER MUST BELONG TO THE SOURCE TYPE, AND NOTHING CHECKS THAT FOR YOU.**
A mismatched pair (e.g. VIDEO_ADS with LEAD_FORM_SUBMIT) is accepted by this tool,
by the platform and by LinkedIn, with no error at any layer — it just builds an
audience that can never populate, because the engagement it describes cannot
happen. Verified on stage. Always take the trigger from the source type's own
`triggers` list in step 1; never carry one over from another source type.
- Requires a connected LinkedIn channel on the account.
- **NEVER re-create the audience because it shows no members.** Zero right after
creation is the normal state; creating it again just makes a duplicate.
- This audience type NEVER reports contact or company counts the way a firmographic
audience does. It lives on LinkedIn, so only LinkedIn's own match count applies.
- WEBSITE additionally requires the LinkedIn Insight Tag installed and active on the
pages the URL rules match. Without it the audience stays empty indefinitely, no
matter how long you wait — mention this whenever you build a WEBSITE audience.
- The lookback window doubles as the retention window: it sets both how far back
engagement counts and how long someone stays in the audience.
- Building from sources with no engagement produces an empty audience. If step 2
showed zeros everywhere, raise that with the user instead of creating anyway.
- The rule cannot be edited afterwards. A different trigger or lookback means a new
audience, so confirm the choice before creating when the user was vague.
COMMON ERRORS AND WHAT THEY MEAN:
- "engagement_source_urns is required" — you skipped step 2, or passed a WEBSITE-style
payload for a non-website source type.
- "must be one of [30, 60, 90, 180]" — WEBSITE was given a 365-day lookback.
- "page_set_name / url_match_groups is required" — WEBSITE needs the URL rules, not URNs.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new audience. Prefer something that describes the rule (e.g. 'Video 50% viewers 90d') so it is recognisable later. | |
| page_set_name | No | WEBSITE only: internal label for the URL rule set created on LinkedIn (e.g. 'Pricing and demo pages'). Required when source_platform is WEBSITE. | |
| source_platform | Yes | The `engagementSourceType` chosen from get_linkedin_engagement_source_types — e.g. VIDEO_ADS, SINGLE_IMAGE_ADS, DOCUMENT_ADS, CONVERSATION_ADS, LEAD_GEN_FORMS, ORGANIZATION_PAGES, or WEBSITE. WEBSITE switches this tool to the URL-rule shape. | |
| url_match_groups | No | WEBSITE only: OR-of-ANDs URL expression. The outer list is ORed, rules inside a group are ANDed. For a plain 'any of these pages' list, use one rule per group. Required when source_platform is WEBSITE. | |
| engagement_trigger | Yes | An `engagementTrigger` listed for THAT source type (e.g. FIRST_QUARTILE for VIDEO_ADS, LEAD_FORM_SUBMIT for LEAD_GEN_FORMS, VISIT for WEBSITE). A trigger from a DIFFERENT source type is accepted without error and silently builds an audience that never populates, so take it from this source type's own trigger list. | |
| lookback_window_days | Yes | How far back engagement counts, and how long a member is retained. WEBSITE accepts 30/60/90/180 only; every other source type also accepts 365. | |
| engagement_source_urns | No | LinkedIn URNs to retarget, taken verbatim from the `id` of each chosen search_linkedin_engagement_sources result. Required for every source type EXCEPT WEBSITE, and must be omitted for WEBSITE. Multiple URNs union their audiences. |