# Get music usage

Retrieve the caller's music generation spend for an organization, summarized over rolling day, week, and month windows with a per-engine breakdown.

Use this to see how much headroom remains before the organization's spend cap rejects a generation. Each window reports the current spend and the configured cap (if any).

## Path parameters

**`organization_id`** string required

The organization the usage is scoped to. The caller must belong to it.

## Returns

A usage summary object.

**`organization_id`** string · The organization the usage is scoped to.

**`windows`** array · One entry per rolling window. Each window contains:

- **`window`** string · `day`, `week`, or `month`.
- **`window_start`** string · Start of the window (UTC).
- **`cost_chf`** number · Spend within the window, in CHF.
- **`limit_chf`** number · The organization's configured spend cap for the window, or `null` if none.
- **`by_engine`** array · Per-engine breakdown, each with `engine`, `track_count`, and `cost_chf`.


Example

```bash cURL
curl "https://api.aitronos.com/v1/music/org_abc123/usage" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

usage = client.get("/v1/music/org_abc123/usage")
for window in usage["windows"]:
    print(window["window"], window["cost_chf"], window["limit_chf"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/music/org_abc123/usage",
    headers={"X-API-Key": api_key},
)
for window in response.json()["windows"]:
    print(f"{window['window']}: {window['cost_chf']} CHF")
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/music/org_abc123/usage', {
  headers: { 'X-API-Key': apiKey }
});

const usage = await response.json();
usage.windows.forEach(w => console.log(`${w.window}: ${w.cost_chf} CHF`));
```

**Response:**


```json 200 OK
{
  "organization_id": "org_abc123",
  "windows": [
    {
      "window": "day",
      "window_start": "2026-06-28T00:00:00Z",
      "cost_chf": 2.40,
      "limit_chf": 10.00,
      "by_engine": [
        { "engine": "studio", "track_count": 6, "cost_chf": 2.40 }
      ]
    },
    {
      "window": "week",
      "window_start": "2026-06-22T00:00:00Z",
      "cost_chf": 11.20,
      "limit_chf": 50.00,
      "by_engine": [
        { "engine": "studio", "track_count": 28, "cost_chf": 11.20 }
      ]
    },
    {
      "window": "month",
      "window_start": "2026-06-01T00:00:00Z",
      "cost_chf": 38.60,
      "limit_chf": null,
      "by_engine": [
        { "engine": "studio", "track_count": 96, "cost_chf": 38.60 }
      ]
    }
  ]
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to access this resource.",
    "system_message": "USE_MUSIC_GENERATION capability required",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_def456uvw",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [Create a generation job](/docs/api-reference/music/create-generation)
- [Get pricing sheet](/assets/get-pricing.1269854a1f55d539f852daed275c801b2537623a4e2a270307a2239a4f87a659.4236153a.md)
- [Music Studio overview](/docs/api-reference/music/introduction)