Rate limits and quotas
Per-minute request limits, plan quotas, and which allowances reset: monthly ones on your billing day, standing slots never.
Per-minute rate limits
Rate limiting is per organization, not per key or per connection — minting a second credential does not buy more throughput. Counted over a trailing 60-second window: 60 reads/min (GET), 5 writes/min (POST/PATCH/DELETE) — the same 5-per-minute cap the product's own inspect flow already enforces, so the two layers can't disagree. Going over returns 429 rate_limit_exceeded with RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset and Retry-After headers telling you exactly when to retry.
Plan quotas
- Catalog slot (
max_catalog_size) — spent byanalyze_tiktok_video. Standing, does not reset; dropping a video frees its slot — see below. - Custom niche slot (
max_custom_niches) — spent bycreate_niche. Standing, like an Agent seat; stopping the niche frees it. - Scripts (
max_scripts_per_month) — spent bygenerate_script. Monthly: resets on your billing day. - Trend searches (
max_viral_searches_per_month) — spent bysearch_viral_trendson an uncached hashtag. Monthly: resets on your billing day. - Uncached search misses (
max_viral_misses_per_day) — a secondary daily cap on the same tool. Resets at the start of each UTC day.
Exact allowances per plan are on Plans & limits. Every value is also readable live at GET /v1/usage — free, unmetered, and named in every quota error so an agent can explain the situation without a second call.
GET /v1/usage returns a real resets_at (your next billing day) for scripts, trend searches, Studio slideshows and the API request count, and resets_at: null for the catalog and custom niches, which are standing caps. A reset starts the counter again for the new period; spending is never refunded, so deleting a script doesn't give it back. The daily uncached-search-miss cap reports its own resets_at, the next UTC midnight.max_catalog_size is a standing cap
This is the single most surprising limit in the product: your video catalog cap is total videos analyzed and stored, counted live with no date filter — not a monthly meter. A Creator workspace's 100 slots don't refill with the billing cycle. To free one, drop a video you no longer need (drop_video): its analysis stays viewable, frozen, and the slot frees at the next UTC midnight; undrop_video restores it before then. analyze_tiktok_video is idempotent on a video already in your catalog (re-analyzing costs nothing extra), and a video whose analysis previously failed mid-pipeline can be retried for free — but a genuinely new video always spends a slot. The write rate limit above exists specifically so a runaway loop hits 429 in seconds rather than draining your catalog.