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

# 用量与计费查询

> 查询 API 用量与账单明细

The Syon usage and billing APIs let you retrieve token usage and charges for individual model requests, aggregate usage and billing over a time range, and check the current account balance.

This document describes the API contract. Actual production responses take precedence.

## API overview

| Endpoint                                | Description                                                                 |
| --------------------------------------- | --------------------------------------------------------------------------- |
| `GET /v1/billing/requests/{request_id}` | Retrieve token usage and billing for a single request                       |
| `GET /v1/billing/costs`                 | Retrieve billing totals for the authenticated API key over a time range     |
| `GET /v1/usage`                         | Retrieve token usage totals for the authenticated API key over a time range |
| `GET /v1/billing/balance`               | Retrieve the current account balance                                        |

## Getting started

### Base URL

Use the API Base URL shown in the Syon console. The examples below refer to it as `$TEAMO_BASE_URL`:

bash

```
export TEAMO_BASE_URL="https://syon.com"
```

### Authentication

Send your Syon API key in the `Authorization` header of every request:

http

```
Authorization: Bearer sk-xxx
```

Keep your API key secure. Do not include it in frontend code, public repositories, or logs. All keys and IDs in the examples are fictional.

## Retrieve usage and billing for a single request

Use a request ID to retrieve the token usage and final charge for one model call.

http

```
GET /v1/billing/requests/{request_id}
```

### Path parameters

| Parameter    | Type        | Required | Description                           |
| ------------ | ----------- | -------- | ------------------------------------- |
| `request_id` | UUID string | Yes      | Request ID returned by the model call |

### Request example

bash

```
curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"
```

### Response example

json

```
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1784081234,
  "model": "gpt-5.4",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cached_write_tokens": 800,
    "cached_read_tokens": 200,
    "total_tokens": 2500
  },
  "amount": {
    "value": "0.012680",
    "currency": "USD"
  }
}
```

### Token fields

| Field                 | Description                             |
| --------------------- | --------------------------------------- |
| `input_tokens`        | Input tokens that did not use the cache |
| `output_tokens`       | Tokens generated by the model           |
| `cached_write_tokens` | Tokens written to the prompt cache      |
| `cached_read_tokens`  | Tokens read from the prompt cache       |
| `total_tokens`        | Sum of all token categories above       |

Token categories that do not apply or are not provided by the upstream service return `0`.

## Retrieve billing for a time range

Retrieve billing totals for the authenticated API key over a time range. The basic response contains aggregate data only, not individual request records.

http

```
GET /v1/billing/costs
```

### Query parameters

| Parameter    | Type    | Required | Description                         |
| ------------ | ------- | -------- | ----------------------------------- |
| `start_time` | integer | Yes      | Start of the query range, inclusive |
| `end_time`   | integer | Yes      | End of the query range, exclusive   |

The query range must not exceed 90 days. Longer ranges return `400 invalid_request`.

### Request example

bash

```
curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"
```

### Response example

json

```
{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "total_amount": {
    "value": "1.280000",
    "currency": "USD"
  },
  "requests": 86
}
```

## Retrieve token usage for a time range

Retrieve aggregate token usage for the authenticated API key over a time range.

http

```
GET /v1/usage
```

### Query parameters

| Parameter    | Type    | Required | Description                         |
| ------------ | ------- | -------- | ----------------------------------- |
| `start_time` | integer | Yes      | Start of the query range, inclusive |
| `end_time`   | integer | Yes      | End of the query range, exclusive   |

The query range must not exceed 90 days. Longer ranges return `400 invalid_request`.

### Request example

bash

```
curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"
```

### Response example

json

```
{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "usage": {
    "input_tokens": 120000,
    "output_tokens": 30000,
    "cached_write_tokens": 10000,
    "cached_read_tokens": 80000,
    "total_tokens": 240000
  },
  "requests": 86
}
```

## Retrieve the account balance

Retrieve the available balance for the account associated with the current API key.

http

```
GET /v1/billing/balance
```

This endpoint does not accept query parameters. The API key identifies the account.

### Request example

bash

```
curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"
```

### Response example

json

```
{
  "balance": {
    "value": "85.320000",
    "currency": "USD"
  }
}
```

## Error handling

When an API call fails, the response body contains a stable error code and a message that helps diagnose the problem.

json

```
{
  "error": {
    "code": "invalid_request",
    "message": "end_time must be greater than start_time"
  }
}
```

### Common error codes

| HTTP status | `error.type` / `error.code`       | Description                                                                   |
| ----------- | --------------------------------- | ----------------------------------------------------------------------------- |
| `400`       | `invalid_request`                 | Invalid request parameters, such as an invalid time range                     |
| `401`       | `missing_auth_credential` / `401` | The API key is missing                                                        |
| `401`       | `invalid_api_key`                 | The API key is invalid                                                        |
| `404`       | `not_found`                       | The request record does not exist or is not accessible to the current API key |
| `429`       | `rate_limit_exceeded`             | Too many requests; retry later                                                |
| `500`       | `internal_error`                  | Internal service error                                                        |

## Recommendations

* Use the same `start_time` and `end_time` when reconciling usage and billing so both queries use the same scope.
* Prices may change. Use the `amount` returned with historical billing records instead of recalculating past charges from the current price list.
* Configure reasonable timeouts and retries. Use exponential backoff for `429` and `5xx` responses.