Plan entitlements
Solo is the display name of the starter tier — accounts.plan_tier and the API still
say starter.
Active Watches is the fan-out fuse, not the axis you shop on: one Query claims one Watch
per search per enabled Source, and the cap sits well above what a plan’s queries produce in
normal use. You meet the Query cap first.
Credit packs top up your balance but never change the limits above — those move only with
the plan.
Terms per search
A search carries either a singlequery or a list of terms, never both. A term list is
OR’d into one upstream request, so a brand plus its variants costs one poll and one
tick — the same as a single term. Your plan caps the list length.
terms is accepted only on the Sources whose own search supports boolean OR, measured
live rather than read off their docs:
Sending
terms to one of the last three answers 400 VALIDATION naming the Source. It
is never split into several Watches behind your back — that would be a surprise invoice.
Plan features
Beyond the four figures above, a plan also unlocks a short list of dashboard features — capabilities a tier has or does not have, rather than has more of:
These gate the dashboard only. Nothing on
/v1 is ever gated by plan features — every
plan reaches the full pull surface, metered by credits and bounded by the request quota
above. A plan change never makes an API call that used to work start failing.
Request quota
/v1/* is limited per Account (not per API key) in a rolling 60-second window, at the
requests-per-minute figure for your plan. Exceeding it returns 429 with
code: "TOO_MANY_REQUESTS"; see Errors — Rate limits for the
envelope and the RateLimit-* / Retry-After headers.
Because the quota is per Account, extra API keys do not buy extra throughput.
Watch entitlements
Watch limits are enforced at two levels, and the stricter one wins.Minimum interval
refresh_interval_seconds: 15 is rejected with 400 VALIDATION even though the
Source itself allows it.
AI answers floors at 6 h on every plan — the Source floor wins, and a run
there is a paid prompt rather than a feed fetch.
The maximum is 86400s (24 h) on every plan and Source, except AI answers,
which allows up to 604800s (7 days) for the same reason.
A slow Watch trades coverage for cost: each tick reads one page of the Source, so a
busy term polled daily reports what fits in that page and misses whatever scrolled past
it in between. Pick the slow end for terms that are quiet, not for terms that are noisy.
Active Watch cap
Creating a Watch checks the plan cap account-wide across all Sources first, then the per-Source cap (Vinted 50, every other Source 20). On Free the account-wide cap of 1 is what you hit — the per-Source numbers only become reachable on Pro. Both rejections are 400VALIDATION.
Downgrades pause what no longer fits
Moving to a lower plan does not delete Watches. Any Watch that now breaks the new entitlements — polling faster than the new minimum, or beyond the new cap — is paused withpausedReason: plan_entitlement. Oldest Watches are kept first; the newest ones are
paused.
Nothing resumes automatically. After upgrading again, call
POST /v1/{source}/watches/{id}/resume per Watch. Resume re-checks the cap and interval,
so it fails while the Watch still exceeds them.
A Watch paused by support (
pausedReason: admin_paused) cannot be resumed with the API —
it returns 409 CONFLICT.