# Usage

> Monitor credit consumption, allocation, and per-API breakdown (synchronous, 200).

- **Endpoint:** `GET https://api.nyne.ai/usage`
- **Group:** Account APIs (https://api.nyne.ai/documentation/account.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Synchronous - the response is returned inline.
- **HTML version:** https://api.nyne.ai/documentation/account/usage

A single synchronous endpoint to view all API usage across enrichment and search requests: credits consumed, allocation, remaining balance, and detailed per-API breakdowns. Without `month`/`year`, it reports the active billing period. Supplying both selects that calendar month (future periods are rejected with `invalid_date`). For prepaid accounts, usage and available credits are workspace-scoped across every API key in that workspace; legacy manual-billing accounts remain scoped to the authenticated key. The response reports credits, not dollars: the monetary price per credit is determined by the account's subscription or credit-purchase tier. Usage checks are free.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `month` | integer | no | Calendar month to report (1-12). Omit both month and year to use the active billing period. | 12 |
| `year` | integer | no | Calendar year to report (2020-2030). Supply it together with month; omit both to use the active billing period. | 2026 |

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Usage | 0 | Monitoring endpoint - usage checks are free |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Usage statistics retrieved |
| `400` | invalid_month / invalid_year / invalid_date (future months are rejected) |
| `401` | missing_api_key / invalid_api_key / missing_api_secret / invalid_api_secret |
| `403` | api_key_disabled |
| `429` | rate_limit_exceeded |
| `500` | internal_error |

## Example request

### cURL

```bash
curl https://api.nyne.ai/usage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

### Python

```python
import requests

resp = requests.get(
    "https://api.nyne.ai/usage",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/usage", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
  },
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/usage");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
  ],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "month": 12,
  "year": 2024,
  "period": "2024-12",
  "period_type": "calendar_month",
  "scope": {
    "type": "workspace",
    "workspace_id": 1234,
    "authenticated_api_key_id": 5678
  },
  "credits_used": {
    "total": 68,
    "search": 45,
    "enrichment": 23
  },
  "requests_count": {
    "total": 25,
    "search": 15,
    "enrichment": 10
  },
  "limits": {
    "monthly_allocation": 10000,
    "available_credits": 9932,
    "is_unlimited": false
  },
  "breakdown": {
    "search_results_returned": 45,
    "enrichments_performed": 23,
    "total_credits_consumed": 68
  }
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt