Credits & rate limits

Data keys are metered in credits. A search costs more than a read because it queries the whole index. Brand keys are never metered.

Credit costs

Call	Type	Description
GET /v1/creators/search	10 credits	One search query, regardless of page size (up to 100 records).
GET /v1/creators/{pk}	1 credit	One profile read.

Monthly budgets

Plan	Type	Description
Starter ($49/mo)	25,000	2,500 searches or 25,000 reads. 60 requests/minute.
Growth ($199/mo)	150,000	15,000 searches or 150,000 reads. 120 requests/minute.
Scale ($499/mo)	500,000	50,000 searches or 500,000 reads. 300 requests/minute.

Budgets reset on the first of each calendar month (UTC). Unused credits do not roll over. Track usage on the keys page.

At the caps

Exceeding the per-minute rate limit:

429

{ "error": "Rate limit exceeded (60/min on Starter plan).", "code": "RATE_LIMITED" }

Exhausting the monthly credit budget:

402

{
  "error": "Monthly credit budget exhausted (25,000/25,000 used). Upgrade at https://api.ugcroster.com/keys or wait for the period to reset.",
  "code": "CREDITS_EXHAUSTED"
}

On 429, back off and retry after the window resets (check the X-RateLimit-Reset header). On 402, retrying is pointless until the period resets or the plan changes. Treat it as terminal for the billing period.

Check usage programmatically

GET /v1/usagereturns the calling key's plan, credit balance and rate limit. It is never metered and has its own 60/min budget, so poll it freely from dashboards or agents.

request

curl "https://api.ugcroster.com/v1/usage" \
  -H "Authorization: Bearer rsk_live_..."

response 200 (data key)

{
  "data": {
    "key_type": "data",
    "plan": "growth",
    "period": "202609",
    "credits": { "used": 41230, "limit": 150000, "remaining": 108770 },
    "requests_this_period": 5211,
    "rate_limit_per_minute": 120,
    "metered": true
  }
}

Brand keys get "metered": false with null credit fields: there is no budget to report.

Spending fewer credits

Searches are the expensive call, so make each one count: filter server-side instead of paginating broad queries (14 filters exist: use follower_min, engagement_min, state, has_email rather than fetching pages and filtering in your code), take the maximum limit=100 per page, and cache profile reads on your side: directory records do not change minute to minute.