> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiohub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Query your own usage logs and usage statistics through the user management API or the current API key.

Usage queries have two authentication modes. Usage logs and summary endpoints use a signed-in session or management access credential. The current API key usage endpoint uses the `sk-` API key itself.

## Query usage logs

```text theme={"system"}
GET /api/log/self?p=1&page_size=20
```

<ParamField path="p" type="integer">
  Page number, starting from `1`.
</ParamField>

<ParamField path="page_size" type="integer">
  Number of records per page.
</ParamField>

<ParamField path="type" type="integer">
  Filter by log type.
</ParamField>

<ParamField path="token_name" type="string">
  Filter by API key name.
</ParamField>

<ParamField path="model_name" type="string">
  Filter by model name.
</ParamField>

<ParamField path="group" type="string">
  Filter by group.
</ParamField>

<ParamField path="request_id" type="string">
  Filter by request ID.
</ParamField>

<ParamField path="start_timestamp" type="integer">
  Start time as a Unix timestamp.
</ParamField>

<ParamField path="end_timestamp" type="integer">
  End time as a Unix timestamp.
</ParamField>

The response includes your usage records, such as model, API key, group, token usage, cost, and call status.

## Query usage summary

```text theme={"system"}
GET /api/log/self/stat?start_timestamp=1700000000&end_timestamp=1700100000
```

Returns usage summary fields for the selected time range, such as `quota`, `rpm`, and `tpm`. For reconciliation, rely on console usage logs and balance changes.

## Query current API key usage

```bash theme={"system"}
curl https://api.aiohub.org/api/usage/token \
  -H "Authorization: Bearer sk-your-api-key"
```

This endpoint returns the usage summary for the current `sk-` API key. It is not the signed-in user's all-API-key list endpoint.

By default, the `data` field returns the current API key quota status:

```json theme={"system"}
{
  "success": true,
  "message": "ok",
  "data": {
    "total_granted": 2,
    "total_used": 0.5,
    "total_available": 1.5,
    "unlimited_quota": false,
    "expires_at": 0
  }
}
```

`total_granted`, `total_used`, and `total_available` reflect the site's current quota display units. The response does not include a unit or symbol. `expires_at` is a Unix-second timestamp; `0` means no expiry is set.

## Query current API key usage for a time range

```bash theme={"system"}
curl "https://api.aiohub.org/api/usage/token?start_timestamp=1700000000&end_timestamp=1700100000" \
  -H "Authorization: Bearer sk-your-api-key"
```

The same endpoint accepts `start_timestamp` and `end_timestamp` for a time-range summary. Use it for scripts that only have an API key and do not have a signed-in session or management access credential. It summarizes only the current API key's own quota consumption and does not return log details.

<ParamField path="start_timestamp" type="integer" required>
  Start time as a Unix-second timestamp. The range includes this second. Send it together with `end_timestamp`; do not send millisecond timestamps.
</ParamField>

<ParamField path="end_timestamp" type="integer" required>
  End time as a Unix-second timestamp. The range includes this second. Send it together with `start_timestamp`; `end_timestamp` must be greater than or equal to `start_timestamp`.
</ParamField>

When a valid range is requested, `data` includes `range_used`:

```json theme={"system"}
{
  "success": true,
  "message": "ok",
  "data": {
    "total_granted": 2,
    "total_used": 0.5,
    "range_used": 0.12,
    "total_available": 1.5,
    "unlimited_quota": false,
    "expires_at": 0
  }
}
```

`range_used` uses the same site quota display setting and is rounded to 6 decimal places. Ranges with no usage return a successful response with `range_used: 0`. Other query parameters are ignored. Disabled or expired API keys cannot query this endpoint; exhausted API keys can still query their own historical summary.

## Troubleshooting

* If a record is missing, check the time range and page number first.
* Cross-filter by API key name, model, group, and time window.
* If an automation script only has an API key, use `/api/usage/token` for the current API key summary and add `start_timestamp` / `end_timestamp` for time-range usage.
* Costs and token counts follow the console usage logs.