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

# Usage-log API

> Read account-level NexusAPI usage logs for reconciliation and audit.

`api.nexusapi.link` is a **read-only usage-log gateway** separate from the console and model relay. It reads consumption logs for the account that owns the credential. It cannot call models, add credit, or perform management actions.

## Basics

| Item                   | Value                                         |
| ---------------------- | --------------------------------------------- |
| Base URL               | `https://api.nexusapi.link`                   |
| Endpoint               | `GET /v1/logs`                                |
| Recommended credential | System access token                           |
| Scope                  | The owning account's usage logs, newest first |

Create a system access token in **Console → Personal settings → Generate token**, then send it only in this header:

```http theme={"system"}
Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN
```

<Warning>
  **Do not confuse credentials**

  Model calls use the API key created in Token Management. The usage-log API should use the system access token. The latter cannot call models, but it exposes account-level usage and must be protected like a secret.
</Warning>

## Query parameters

All parameters are optional. For routine reconciliation, query one day or week at a time.

| Parameter    | Meaning                                                                      |
| ------------ | ---------------------------------------------------------------------------- |
| `start_time` | Unix seconds or an RFC3339 start time.                                       |
| `end_time`   | Unix seconds or an RFC3339 end time; it cannot be earlier than `start_time`. |
| `page`       | Page number, starting at `1`; default `1`.                                   |
| `page_size`  | Records per page; default `10`, maximum `50`.                                |

The API does not currently provide server-side filters for model, group, or token name. Filter the returned account data locally. `page × page_size` cannot exceed `100000`.

## Example

```bash theme={"system"}
curl -G 'https://api.nexusapi.link/v1/logs' \
  -H 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --data-urlencode 'start_time=2026-06-01T00:00:00Z' \
  --data-urlencode 'end_time=2026-06-02T00:00:00Z' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=50'
```

When `data` is empty or contains fewer records than `page_size`, you have reached the last page. The endpoint intentionally does not return a total count.

## Important response fields

| Field                                 | Meaning                                              |
| ------------------------------------- | ---------------------------------------------------- |
| `time`                                | Request time in UTC / RFC3339.                       |
| `token_name`                          | Name of the API key used by the request.             |
| `group` / `model`                     | Actual token group and model recorded.               |
| `use_time` / `first_byte`             | Total duration and time to first byte, in seconds.   |
| `prompt_tokens` / `completion_tokens` | Input and output tokens.                             |
| `cost`                                | Recorded charge in USD.                              |
| `ip`                                  | Source IP when recorded.                             |
| `request_id`                          | Request identifier for reconciliation.               |
| `request_path`                        | Actual API path, for example `/v1/chat/completions`. |

Internal channel data, raw quota, and full billing calculation are intentionally not returned.

## Errors and frequency

| HTTP status | What to do                                                              |
| ----------- | ----------------------------------------------------------------------- |
| 400         | Check time format, order, and pagination depth.                         |
| 401         | Regenerate the system access token; do not send it to support.          |
| 429         | Follow `Retry-After` before retrying.                                   |
| 503         | Wait for the value in `Retry-After`, then try again.                    |
| 500         | Keep `X-Request-Id`, time, and the response text, then contact support. |

Use scheduled incremental pulls, not second-by-second polling. For a suspected billing issue, retain both the query range and the model-call Request ID.