Credits and limits

Credits

GET /credits (scope credits:read) returns the team's current balance plus a paginated ledger of credit movements:

bash

curl -s https://viraloop.io/api/v1/credits \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

bash

viraloop credits --json

Query parameters: page, limit (max 100) and type to filter entries by recurring, topup, spending, trial, spin, reward or refund.

What costs credits:

POST /influencers/{id}/videos (talking-head video): 20 credits per video, deducted up front.
POST /influencers (create influencer): 10 credits for the optional animated preview; when the team is out of credits the preview is skipped and the influencer is still created.

Content generation (POST /generations) and posting (POST /posts) consume no credits.

If a paid generation fails (provider error or timeout), the deducted credits are refunded automatically and show up in the ledger as a refund entry referencing the original spend.

Running out of credits returns 402 with error type insufficient_credits; top up at https://viraloop.io/settings/billing. Plan quotas (automations, content saves) are separate from credits and return 403 with usage_limit_reached.

Rate limits

Limits are applied per API key:

Every endpoint: 300 requests per 60 seconds (default)
POST /generations: 10 requests per 300 seconds
POST /posts: 60 requests per 300 seconds

Exceeding a limit returns 429 with error type rate_limited and a Retry-After header (seconds). Wait that long, then retry:

json

{
	"success": false,
	"error": {
		"type": "rate_limited",
		"message": "Too many requests, slow down"
	}
}

The generation limit is deliberately tight because each call is synchronous and can produce up to 10 suggestions; batch with count instead of looping single-suggestion calls.

Credits and limits

Credits

Rate limits

Want the short version?