# 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.