# Get usage

`GET https://api.vidmoat.com/v1/usage`

- Scope: `account.read`
- Cost: Free

Request counts (with the error split) and credits spent, for the whole account and for this key's app, for building your own dashboard or a spend alarm.

### Query parameters

- `days` (integer, optional, default `30`): Window length in days, 1 to 90.

## Response

Returns `200`.

### Response fields

- `window` (object): `{ days, since }`.
- `account` (object): `{ credits, requests, errors, successes, byAction, balance }` for every credential on the account. `credits` is net of refunds.
- `app` (object): The same counts for this key's app (or this key, when it has no app), with `appId` and `keyId`.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `days` is not a positive number. |

## Request examples

```bash curl
curl "https://api.vidmoat.com/v1/usage?days=30" \
  -H "Authorization: Bearer $VIDMOAT_KEY"
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/usage?days=30', {
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.get(
    "https://api.vidmoat.com/v1/usage?days=30",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "window": { "days": 30, "since": "2026-09-03T12:00:00.000Z" },
  "account": {
    "credits": 12, "requests": 340, "errors": 5, "successes": 335,
    "byAction": { "project_create": { "count": 3, "credits": 0 } },
    "balance": { "remaining": 4488, "perMonth": 6000, "resetsAt": "2026-11-01T00:00:00.000Z" }
  },
  "app": { "appId": "app_xyz", "keyId": "key_abc", "credits": 0, "requests": 120, "errors": 2, "successes": 118, "byAction": {} }
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/account/get-usage
Previous: [Get the current account](https://developer.vidmoat.com/developer/docs/api/account/get-me.md)
Next: [Get the command schema](https://developer.vidmoat.com/developer/docs/api/account/get-command-schema.md)
All documentation: https://developer.vidmoat.com/llms-full.txt