# Get Account Usage API

Canonical docs: https://platform.sonilo.com/docs/api/get-usage
Source path: /docs/api/get-usage
Runtime API host: https://api.sonilo.com/v1

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Endpoint

GET /v1/account/usage

## Summary

Use this endpoint for usage dashboards, quota checks, eval account health, and remaining-credit preflight checks.

## Use This For

- Showing recent API usage by day and summary totals.
- Checking balance before real audio generation so agents do not create placeholder audio.
- Pairing with GET /v1/account/services before dashboard UI code calls GET /v1/account/usage.

## Request

- days: optional integer query parameter. Example: days=30.

## Response And Errors

- 200 returns summary totals plus daily usage rows.
- 401 auth_invalid means the Authorization header is missing or the API key is invalid.
- 403 forbidden means the account cannot access usage data.
- 404 not_found means the URL is wrong; use https://api.sonilo.com/v1/account/usage, not a docs URL or local proxy route.
- For dashboards, call GET /v1/account/services first, then GET /v1/account/usage?days=30 from server-side code.
- Do not call /usage, /api/usage, /account/usage, platform.sonilo.com, docs.sonilo.com, or a docs page as the runtime usage API.
- If a later generation call returns 402 payment_required or insufficient_balance, report the account state instead of creating placeholder audio.

## Example

```bash
curl "https://api.sonilo.com/v1/account/usage?days=30" \
  -H "Authorization: Bearer sk_your_api_key"
```

## Shared Error Handling

- 401 auth_invalid: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits before rerunning; do not create fake audio.
- 403 forbidden: the key is valid but the account or service permission is missing.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 429 rate_limit_exceeded: honor Retry-After and retry with backoff.

## Endpoint Vocabulary

- GET /v1/account/services
- GET /v1/account/usage
- POST /v1/text-to-music
- POST /v1/video-to-music
- POST /v1/audio-ducking
- POST /v1/text-to-sfx
- POST /v1/video-to-sfx
- GET /v1/tasks/{task_id}