Skip to main content
A list is a durable, named set of entities of one type — a competitor set, a creator shortlist, a product watchlist. Lists exist so that a set you care about has an identity of its own, instead of being reassembled from a spreadsheet every time.

​
Creating one

A list holds one entity_type. Mixing shops and creators in one set makes the metrics incomparable, so the API does not allow it — create two lists and relate them on your side.

​
Reading it back

GET /lists/{id}/items returns the full record for every member, measured over whatever period you ask for. This is the main reason to use lists: refreshing a tracked set is one call.
Change period and you get the same set measured over a different window — which makes week-over-week comparison a matter of two calls rather than a stored history you have to maintain.

​
Adding and removing

Adds are idempotent — IDs already present are ignored, so you can push your full set each sync without diffing first. A list holds up to 1,000 items.
Build a list straight from a search: page through the results, collect the id values, and post them. That turns a one-off query into a set you can track.

​
What lists unlock

Trackers

Point a tracker at a list and Unif re-checks every member on a schedule, posting a webhook when one crosses a threshold.

Cheap refreshes

Re-reading a list by ID skips resolution entirely, so a daily refresh costs less than re-enriching from URLs.

​
Lists are not queries

A list is a fixed set of IDs. It does not re-run a search, and it does not gain members when new entities start matching the criteria that produced it. When you want “everything currently matching these filters”, that is a tracker with a search source — it re-runs the query each cycle and tells you what entered or left.