# getUsage

> Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json.

`GET https://api.map.audio/v1/usage`

Get usage by key and meter

Meter totals for the account per API key and meter: render-minutes, rendered audio seconds, compute time, and the free commands' own meters. `from` and `to` are UTC days, at most a year apart and at most 90 days back, as usage is kept that long. Requests made with a map.audio sign-in have `keyId: null`. Free; GET /v1/credits shows what is left to spend.

Auth: `Authorization: Bearer` with an API key or a map.audio access token. Not an MCP tool: Per-key meter totals are for dashboards and audits; get_credits shows the render-minutes an agent can still spend.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | no | First UTC day, YYYY-MM-DD, at most 90 days back. Default: the first of this month. |
| `to` | query | string | no | Last UTC day, included. Default: today. |

## Example

```sh
curl -sS "https://api.map.audio/v1/usage?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $MAP_API_KEY" \
  -H "Map-Version: 2026-11-01"
```

### 200: This month so far

```json
{
  "object": "usage",
  "from": "2026-11-01",
  "to": "2026-11-01",
  "data": [
    {
      "keyId": "key_01M6BPR91W1E1YGMF0P6TAZZNG",
      "meter": "audioSeconds",
      "quantity": 252.8
    },
    {
      "keyId": "key_01M6BPR91W1E1YGMF0P6TAZZNG",
      "meter": "computeMs",
      "quantity": 61408
    },
    {
      "keyId": "key_01M6BPR91W1E1YGMF0P6TAZZNG",
      "meter": "renderMinutes",
      "quantity": 4.214
    }
  ]
}
```

### 400: Invalid request

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "from must be a date as YYYY-MM-DD; got \"yesterday\".",
    "param": "from",
    "retryable": false,
    "jobId": null,
    "docUrl": "https://map.audio/developers/music-api/errors#invalid_request",
    "requestId": "9a3f7c2e5b1d8f40-LHR"
  }
}
```

## Responses

- `200`: Usage.
- `400`: Invalid request
- `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue.

## Errors

- [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request)