Rate limits and quotas
Per-minute request limits, plan quotas, and the single most surprising thing about our metering: most allowances do not currently reset.
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 — see below. - Custom niche slot (
max_custom_niches) — spent bycreate_niche. Standing, like an Agent seat. - Scripts (
max_scripts_per_month) — spent bygenerate_script. Monthly by design, but see the reset caveat below. - Trend searches (
max_viral_searches_per_month) — spent bysearch_viral_trendson an uncached hashtag. Monthly by design, same caveat. - Uncached search misses (
max_viral_misses_per_day) — a secondary daily cap on the same tool. This is the only meter that genuinely 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 resets_at: null for the catalog, custom niches, scripts, trend searches and API request count — not withheld information, but the literal truth: the monthly reset job has no scheduled caller anywhere in this product yet, so those meters accumulate rather than clearing at the start of a new billing cycle. Every "per month" allowance is a lifetime cap in practice until that changes. Do not build automation that assumes a script or trend-search allowance frees up next cycle — today it will not. The one exception is the daily uncached-search-miss cap, which self-heals every UTC day and does report a real resets_at.max_catalog_size is a standing cap
This is the single most surprising limit in the product: your video catalog cap is total videos ever analyzed and stored, counted live with no date filter — not a monthly meter. A Creator workspace's 100 analyses are gone for good once spent; there is no cycle that refills them. 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 a cap that never comes back.