# API key information and usage

> Read-only endpoints that describe the calling API key, its recent requests and its daily usage statistics.

**Status: experimental.**

These endpoints exist and work with any active API key, but they are not part of the published OpenAPI schema. Treat their response fields as subject to change, and do not build critical logic on them.

All three use `Authorization: Bearer YOUR_API_KEY`, take no body, and only ever describe the key that makes the call.

## Key information

`GET https://moknah.io/api/v1/key/info/`

Returns one JSON object:

| Field | Description |
| --- | --- |
| `id`, `name`, `key_prefix` | Identity of the key. `key_prefix` is its first characters. |
| `status` | `active`, `inactive`, `suspended` or `expired`. |
| `engine` | Voice type of the key: `standard` or `advanced`. |
| `allowed_services` | List of `tts`, `tts_ws`, `stt`, `stt_ws`. |
| `credit_limit`, `credits_used`, `credits_remaining`, `usage_percentage` | The key's own credit cap and consumption. A `credit_limit` of `0` means no cap. |
| `rate_limit_per_minute` | Requests per minute allowed for this key. |
| `total_requests`, `last_used_at`, `expires_at`, `created_at` | Usage and lifetime. |

`credits_remaining` here is what is left of the key's own cap. It is not the account's credit balance.

## Request log

`GET https://moknah.io/api/v1/logs/`

| Query parameter | Default | Description |
| --- | --- | --- |
| `limit` | 20 | Number of rows, at most 100. |
| `offset` | 0 | Rows to skip. |

Response: `{"count": <total rows>, "results": [...]}`, newest first. Each row has `id`, `service`, `endpoint`, `method`, `status_code`, `response_time`, `credits_used`, `ip_address`, `error_message` and `created_at`.

## Daily statistics

`GET https://moknah.io/api/v1/statistics/`

| Query parameter | Default | Description |
| --- | --- | --- |
| `days` | 30 | How many days back to include. |

Response: `{"period_days": <days>, "results": [...]}`, newest first. Each row has `date`, `service`, `total_requests`, `successful_requests`, `failed_requests`, `success_rate`, `total_credits_used` and `avg_response_time`.

## Example

```bash
curl "https://moknah.io/api/v1/key/info/" -H "Authorization: Bearer YOUR_API_KEY"
curl "https://moknah.io/api/v1/logs/?limit=5" -H "Authorization: Bearer YOUR_API_KEY"
curl "https://moknah.io/api/v1/statistics/?days=7" -H "Authorization: Bearer YOUR_API_KEY"
```

## Credits

These calls are free.
