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.
Start with 50 free credits
New API customers can claim 50 one-time credits after verifying their email. No card required; subject to availability and abuse limits. Trial credits have a separate balance and do not renew monthly. Monthly subscription credits are used first, then trial credits, then purchased credits. Add a pack from $25 to continue with the same key.
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 ($98/mo) | 25,000 | 2,500 searches or 25,000 reads. 60 requests/minute. |
| Growth ($398/mo) | 150,000 | 15,000 searches or 150,000 reads. 120 requests/minute. |
| Scale ($998/mo) | 500,000 | 50,000 searches or 500,000 reads. 300 requests/minute. |
Budgets reset on the first of each calendar month (UTC). Unused monthly credits do not roll over. Purchased credits roll over and are used only after your monthly allowance. Prepaid access needs no monthly subscription; it runs at 60 requests/minute. Track usage on the keys page.
Prepaid credits
Buy 5,000 credits for $25, 25,000 for $125, or 100,000 for $500 in your console. No monthly subscription is required. Auto-reload is optional and off by default. No overage charges. Existing subscribers keep their current terms.
Optional auto-reload
In Credits & billing, choose a credit pack, the available-balance threshold that triggers it, and a monthly dollar limit. Auto-reload is off by default. Save a card through Stripe and explicitly authorize the charges to enable it. If your balance is already below the threshold, enabling may trigger one reload immediately.
Checks run about once a minute. Each successful payment adds one pack. The monthly limit resets at 00:00 UTC on the first day of the month; manual purchases are separate. Failed payments pause auto-reload instead of retrying automatically. Requests still stop at zero until payment succeeds. Disable future reloads anytime in the console; payments already processing may complete.
At the caps
Exceeding the per-minute rate limit:
429
{ "error": "Rate limit exceeded (60/min on Starter plan).", "code": "RATE_LIMITED" }Exhausting monthly and purchased credits:
402
{
"error": "Not enough credits for this request (0 remaining). Buy credits or upgrade at https://api.ugcroster.com/keys, or wait for the monthly 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 you buy credits, the period resets, or you upgrade. Do not keep retrying without a balance change.
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.