Create an engagement watch
Watch LinkedIn posts and collect the people who engage with them as leads.
Two kinds. A topic watch takes a boolean keyword query ("lean manufacturing" OR "visual management") and surfaces whoever liked the matching posts. A company watch does the same for one competitor’s own posts — people interacting with a competitor are, by definition, shopping in your category.
Set persona_ids to decide who counts as a lead; the personas are the ones from List personas, so sharpening a persona sharpens every watch using it. Engagers matching no persona are still recorded, so widening a persona later surfaces people already collected rather than only affecting future sweeps.
Cost is max_posts_per_sweep × max_engagers_per_post per sweep, and nothing else. Both default conservatively; raise them once a watch is producing what you expect.
A watch’s kind and target are fixed once created: pointing it somewhere else would leave its collected people describing a subject it no longer has, so create a second watch instead.
Authorizations
Account API key passed in the Authorization header
Query Parameters
Target account UUID. Required for staff callers; ignored for customer API keys.
Body
topic or company.
topic, company Your label for this watch.
1Required for kind=company, and rejected for kind=topic. The competitor's numeric LinkedIn ID.
ISO 3166-1 alpha-2 codes to keep. Omit for no country restriction. This filters engagers; it is never written onto them.
Defaults to true.
Required for kind=topic, and rejected for kind=company. A LinkedIn boolean query, passed through as written: "lean manufacturing" OR "visual management".
How many engagers are read per post. Defaults to 25. Spend per sweep is this times max_posts_per_sweep.
1 <= x <= 500How many posts one sweep looks at. Defaults to 10.
1 <= x <= 100Personas deciding which engagers count as leads, from GET /v2/personas. Omit to keep everyone who engaged. Engagers matching none are still recorded, so widening a persona later surfaces people already collected.
Response
OK
ISO 3166-1 alpha-2 codes to keep. Empty means no country restriction.
A disabled watch is not swept and costs nothing, but keeps its history.
topic or company.
"topic"
Cost dial: how many engagers are read per post. Spend per sweep is this times max_posts_per_sweep.
Cost dial: how many posts one sweep will look at.
Your label for this watch.
"Lean manufacturing"
Personas that decide which engagers count as leads. Empty keeps everyone who engaged.
Company watches only: the competitor's numeric LinkedIn ID.
Topic watches only: the boolean query, exactly as you wrote it.
How many people the last run collected. Zero after a completed sweep means nobody engaged, which is different from the watch not having run.
What the last run did. One of:
- completed: it ran, and last_sweep_engagers_collected says what it found. Zero is a real answer.
- out_of_credits: skipped before spending, because the account could not pay for a single person. This is the one to check when a feed goes quiet — topping up resumes it on the next sweep.
- failed: it ran and something went wrong, usually the provider. Self-correcting, since the next sweep re-reads an overlapping window.
When this watch last ran. Absent until its first sweep.