> For AI agents: the documentation index is at https://platform.detectif.ai/llms.txt. Every page is also available as Markdown by adding `.md` to its path.

# Get your Noesis usage

`GET /v1/detect/usage`

Your Noesis calls and call minutes over the last `days` days (default 30): how many calls and file analyses, seconds of audio, billed minutes and what was charged, and how many run right now. Requires scope `noesis:read`.

## Authentication

Send your API key as `Authorization: Bearer <your API key>`.

## Headers

| Name | Type | Required | Description |
|---|---|---|---|
| `Authorization` | string | yes | `Bearer <your API key>`. Keys are created in the dashboard; see [Authentication](https://platform.detectif.ai/docs/noesis/authentication/). |

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `days` | integer | no | Length of the period in days, ending now (1-90). (1 to 90; default `30`) |

## Response

`200`: Success.

| Field | Type | Required | Description |
|---|---|---|---|
| `request_id` | string | yes |  |
| `object` | string | yes | (always `"noesis.usage"`) |
| `days` | integer | yes |  |
| `period` | object | yes |  |
| `calls` | integer | yes | Calls and file analyses started in the period. |
| `calls_used` | integer | yes | Same as calls (kept for older clients). |
| `streams` | integer | yes |  |
| `files` | integer | yes |  |
| `audio_seconds` | number | yes |  |
| `billed_seconds` | number | yes |  |
| `minutes` | number | yes | Billed call minutes (billed_seconds / 60). |
| `credits_charged` | integer or null | no | What the calls used from your balance. |
| `active_sessions` | integer | yes |  |
| `concurrent_limit` | integer | yes | How many calls or file analyses may run at the same time. |
| `plan` | string | yes | (one of `free`, `unlimited`) |
| `unlimited` | boolean | yes |  |

### Example response

```json
{
  "request_id": "req_8f14e45fceea167a5a36dedd",
  "object": "noesis.usage",
  "days": 30,
  "period": {
    "start": "2026-09-19T09:30:00Z",
    "end": "2026-10-19T09:30:00Z"
  },
  "calls": 12,
  "calls_used": 12,
  "streams": 10,
  "files": 2,
  "audio_seconds": 1284.5,
  "billed_seconds": 1280,
  "minutes": 21.33,
  "active_sessions": 1,
  "concurrent_limit": 2,
  "plan": "free",
  "unlimited": false
}
```

## Errors

| Status | Meaning |
|---|---|
| `400` | The request is invalid, for example an API key in the URL or an unsupported parameter. |
| `401` | The API key is missing, invalid or revoked. |
| `403` | The key lacks the required scope, the e-mail address is not verified, or the account is suspended. |
| `429` | Too many requests, or too many calls and file analyses at the same time. Wait for Retry-After seconds. |
| `500` | Something went wrong on our side. |

Error bodies use the shape described in [Errors](https://platform.detectif.ai/docs/noesis/errors/), with a stable `error.code`.

## Code samples

```bash
curl "https://api.noesis.detectif.ai/v1/detect/usage" \
  -H "Authorization: Bearer $DETECTIF_API_KEY"
```

```python
import os

import requests

resp = requests.get(
    "https://api.noesis.detectif.ai/v1/detect/usage",
    headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}"},
    timeout=30,
)
print(resp.status_code, resp.json())
```

```javascript
const res = await fetch("https://api.noesis.detectif.ai/v1/detect/usage", {
  headers: {
    Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```