RoomScope

Last updated

Credits

Every workspace has a credit wallet that refills each billing period. API calls and dashboard reads draw from the same wallet; the reference lists the class of each operation.

What an operation costs

ClassCredits per callCovers
Cached read1Every read of stored data: rankings, creators, insights, videos, comments, trends, LIVE sessions. Listing API keys (GET /v1/api-keys) is a cached read too.
Follow list4,000GET /v1/creators/{uid}/following or /followers when the list has to be collected fresh (instead of 1).
Comments500GET /v1/videos/{id}/comments when the comments have to be collected fresh (instead of 1).
Profile resolve1,250GET /v1/creators/{uid} when a stale profile is resolved again, on top of the read. Charged only if a profile comes back.
Live refresh1,250POST /v1/live/creators/{uid}/refresh: ask the workers to check a creator now.
Export2,500POST /v1/exports: build a CSV or Excel file.
Webhook delivery1Each webhook an alert rule delivers, including the one a rule test sends.
Free0Managing alert rules, listing and downloading exports, creating and revoking keys, entitlements and usage.

Each operation in the reference shows its class next to its scope. A 202 answer (collection still running) is charged as a cached read.

Monthly allotment

Each calendar month (UTC) the workspace’s plan grants its allotment, on the first metered call or wallet read of the month. Spending in a month cannot go past the allotment. See pricing for the plans.

PlanCredits per month
Free150,000
Starter450,000
Pro3,000,000
Scale12,000,000
Agency / Enterprise36,000,000

When the wallet is empty

A metered call that would go past the cap answers 402 with code credit_cap_exceeded in the usual error envelope. Free operations keep working. The wallet refills at the start of the next month; upgrading mid-month raises the cap.

A failed call is not charged
Credits are reserved when the call starts and released if it fails, so a 4xx or 5xx answer costs nothing. A 2xx or 3xx is charged.

Read the wallet

GET /v1/entitlements returns the plan, limits and the wallet of the current period; GET /v1/usage breaks spending down by operation. Both are free and need the keys:manage scope.

bash
curl "https://api.next.toktokdata.live/v1/entitlements" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY" # data.credits: { "period": "2026-11-01", "monthlyAllotment": …, "hardCap": …, "spent": …, "remaining": … }
Was this page helpful?