One watchlist covers one signal for one audience
Competitor mentions, buying intent, and mentions of your own brand are three different questions. They are three keyword watchlists, not one prompt that lists all three. Three things on a watchlist are shared by everything in it, which is why merging signals breaks them:- The relevance objective is one sentence. Every collected post is scored against it. A sentence covering three signals scores everything as half relevant.
- Intent labels are chosen per watchlist. A merged watchlist spends its label budget describing which signal a post is, instead of what the person wants.
- The product marks up to two labels as default, and the defaults are what it opens the watchlist on. Three signals cannot each get their own default view.
GET /api-team first and read limits.watchlists before you start, or the third create comes back 402. For people and company watchlists, the allowance that runs out first is usually the profile count: GET /api-team reports it as limits.tracked_profiles_and_companies.
A Reddit twin is a fourth create, to POST /api-reddit-watchlist with the same prompt. One watchlist covers one platform, so “on LinkedIn and Reddit” is always two calls. See Choose a watchlist type.
Prompt mode first
Sendprompt unless you already know the exact strings to match. OutX reads the sentence into topic, audience and signal, then writes the keywords, the intent labels and the relevance objective. It is the path the product itself uses.
objective or labels are missing the server generates them in the background, and the create response carries generated, telling you which of the two it had to write.
objective yourself is still better than letting the server infer one from your keyword strings. generated.objective: true means OutX guessed at what you were looking for.
Read with labels=default
A keyword or Reddit watchlist can carry default labels. The product marks up to two when it generates a taxonomy, and opens the watchlist filtered to them, so a user sees the highest-intent bucket rather than everything collected. The API does not do this on its own: omit labels and you get every post, which is the firehose the defaults exist to avoid.
Pass labels=default and the server resolves it to that watchlist’s default keys.
default_labels is what the watchlist considers primary. applied_labels is what actually filtered this response. Both are on every /api-posts response, so you can tell a narrowed feed from a full one without a second call.
Read with labels=default first. Omit labels only when you deliberately want everything, for example when counting collection volume or exporting.
Handle the no-defaults case. Plenty of watchlists have no default labels. There, labels=default applies no filter and default_labels comes back empty. That empty array is your cue to choose labels explicitly: read the watchlist’s label set, pick the ones matching what you are after, and pass those keys instead of working through the unfiltered feed. Full behaviour: Intent labels and defaults.
People and company watchlists
These track a named set rather than a topic. They differ from keyword watchlists in ways that catch agents out:- No prompt mode. You send
profiles(orcompanies). There is nothing to generate. - No intent labels. Every post comes back tagged
"na". Do not poll waiting for tags, andlabels=defaultresolves to no filter. fetchFreqInHoursworks the same as everywhere else. Optional on create and update, allowed values1, 3, 6, 12, 24, 48, 72, default 12.- 200 members per watchlist, and a team-wide entitlement across every watchlist you own.
PUT. Removals are applied before the caps are checked, so swapping members in one call works.
skipped lists the raw inputs that did nothing: unparseable, repeated in the same request, already on the list when adding, or absent when removing. Company watchlists are the same shape with add_companies, remove_companies and companies_count.
Job changes
When a tracked person changes job, that arrives as a row in the same people watchlist feed withpost_type set to job_update. There is no separate endpoint and no intent label on those rows.
When each type starts filling
- Keyword watchlists backfill within minutes, on create and whenever you change
keywordsor send a newprompt. You do not wait for a fetch cycle. - Reddit, people and company watchlists never backfill. They fill from their first fetch cycle onward, so an empty feed shortly after create is expected.
Take inventory before you create
Watchlists count against your plan, and creating a near-duplicate wastes a slot. One call lists every watchlist the team has, all four types:idempotency_key on every create so a retry cannot produce a second copy. See List all watchlists.
Never do these
Next steps
List all watchlists
Every watchlist of every type in one call
Choose a watchlist type
The four types side by side
Intent labels and defaults
How posts get classified and what
default doesGet posts
Read and filter any watchlist’s feed