GET /api-watchlists returns every watchlist the team owns: keyword, Reddit, people and company, in one response. Use it before creating anything, so you reuse or update an existing watchlist instead of adding a near-duplicate that eats a plan slot.
The per-type endpoints (GET /api-keyword-watchlist and friends) each list only their own type and carry the fuller detail for it. This one is the inventory.
Query Parameters
string | array
Restrict to one or more types. Allowed values:
keyword, reddit, people, company. Pass several as comma-separated (type=keyword,reddit) or as repeated params. Omit for all four. An unrecognized value is rejected with a 400.boolean
true returns only paused watchlists, false only active ones. Omit for both.400 naming the offending parameter and the accepted list.
Response Fields
array
The watchlists, newest first by
created_at. Deleted watchlists are never included.number
Number of entries in
data. There is no paging on this endpoint, so it is the full total for the filters you sent.Watchlist Object Fields
string
Watchlist ID. Pass it to
GET /api-posts?watchlist_id=... or to the matching typed endpoint.string
One of
keyword, reddit, people, company. This tells you which typed endpoint owns the watchlist: a keyword watchlist is read and updated at /api-keyword-watchlist, a people one at /api-people-watchlist, and so on. Asking the wrong endpoint for an ID returns 404.string
Watchlist name.
string
URL-friendly slug. Changes only when the watchlist is renamed.
boolean
true when the watchlist is paused. A paused watchlist collects nothing. Resume it with PUT on its typed endpoint and { "disable": false }.string
ISO 8601 timestamp of creation.
array
The label keys the watchlist opens on, which is what
labels=default resolves to on GET /api-posts. Empty when the watchlist has no defaults, which is common: there labels=default filters nothing, so read the watchlist’s label set and choose keys explicitly.Present on keyword and reddit rows only. People and company watchlists have no intent labels, so the field is absent from those rows entirely rather than empty.Error Responses
Frequently Asked Questions
Why does this exist when each type already has a list endpoint?
Why does this exist when each type already has a list endpoint?
To answer “what do we already have” in one call instead of four. An agent that has to find a watchlist by name, check whether a signal is already covered, or clean up a test list would otherwise call every typed endpoint and merge the results.
Does it return the keywords, profiles or labels of each watchlist?
Does it return the keywords, profiles or labels of each watchlist?
No. It returns the identity of each watchlist plus
default_labels on the labelled types. For keywords, profiles, companies, the objective or the full label set, call the typed endpoint with ?id=, for example GET /api-keyword-watchlist?id=....Is there a limit on how many it returns?
Is there a limit on how many it returns?
No paging and no cap.
count is the number of rows in data.Related pages
Design your watchlists
How to lay watchlists out before you create them
Choose a watchlist type
The four types side by side