> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/api-reference/introduction/use.md).

# Usage

### Endpoints

| Method | Path                     | Description                                                  |
| ------ | ------------------------ | ------------------------------------------------------------ |
| GET    | `/api/compat/v1/usage`   | List generation records from `generations` table             |
| GET    | `/api/compat/v1/balance` | Get current credit balance of authenticated user             |
| GET    | `/api/compat/v1/api-key` | Look up the calling API key's name, status, and spend limits |

Auth: `Authorization: Bearer <jwt>` or `x-api-key`.

### GET /api/compat/v1/usage

Query fields:

| Field    | Type     | Required | Notes        |
| -------- | -------- | -------- | ------------ |
| `offset` | `number` | No       | Default `0`  |
| `limit`  | `number` | No       | Default `20` |

Response shape:

| Field                  | Type                                                  |
| ---------------------- | ----------------------------------------------------- |
| `results[]`            | Array of generation rows                              |
| `results[].id`         | `string`                                              |
| `results[].userId`     | `string`                                              |
| `results[].apiKeyId`   | `string \| undefined`                                 |
| `results[].modality`   | `"text" \| "image" \| "video" \| "audio"`             |
| `results[].model`      | `string`                                              |
| `results[].status`     | `"succeeded" \| "failed" \| "aborted" \| "cancelled"` |
| `results[].request`    | `object \| undefined`                                 |
| `results[].usage`      | `object \| undefined`                                 |
| `results[].usdCost`    | `number \| undefined`                                 |
| `results[].durationMs` | `number \| undefined`                                 |
| `results[].createdAt`  | `datetime`                                            |
| `total`                | `number`                                              |
| `offset`               | `number`                                              |
| `limit`                | `number`                                              |

This endpoint currently supports paging only and returns compat generation rows.

#### Response Example

```json
{
	"results": [
		{
			"id": "6a584d837deb305999dda675",
			"userId": "6a38e2554301a757f3721c0c",
			"modality": "image",
			"model": "seedream-4-0",
			"status": "succeeded",
			"request": {
				"model": "seedream-4-0",
				"prompt": "A simple red apple on a white table",
				"n": 1,
				"size": "1920x1920",
				"response_format": "b64_json",
				"stream": true
			},
			"usage": {
				"totalTokens": 14400,
				"generatedImages": 1,
				"outputTokens": 14400
			},
			"usdCost": 0.036,
			"durationMs": 6256,
			"createdAt": "2026-07-16T03:18:27.208Z"
		}
	],
	"total": 1,
	"offset": 0,
	"limit": 20
}
```

### How Tokens and Credits Are Calculated

#### Tokens (`usage`)

`usage` fields are normalized from runtime usage and stored per generation row.

* Text: commonly includes `promptTokens`, `completionTokens`, and `totalTokens`.
* Image: commonly includes `generatedImages`, `outputTokens`, and sometimes `totalTokens`.
* Video: commonly includes `completionTokens` / `totalTokens` when available from provider.

Token fields can vary by model and request type, so not every key is guaranteed on every row.

#### Credits (`usdCost`)

`usdCost` is the final user charge for that generation row.

At settle time, the backend computes the final billable amount using your account pricing policy.

Formula summary:

```
usdCost = final billable amount for this generation
```

In usage records, `usdCost` is the amount deducted for that request.

### GET /api/compat/v1/balance

Response shape:

| Field           | Type     |
| --------------- | -------- |
| `creditBalance` | `number` |

Response example:

```json
{
	"creditBalance": 12.345
}
```

### GET /api/compat/v1/api-key

Looks up the calling API key's name, status, and configured spend caps (daily/weekly/monthly/total).

**Auth: `x-api-key` only.** This endpoint reports on *the specific key used to authenticate the request*, so a JWT-authenticated session (no key attached) returns `403`.

The response is scoped to the key itself and deliberately excludes the owning account's credit balance — a key holder is not necessarily the account owner. Use `GET /api/compat/v1/balance` for the account balance.

Response shape:

| Field                                   | Type                  | Notes                                                                                                                            |
| --------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                  | `string`              | The key's display name.                                                                                                          |
| `isActive`                              | `boolean`             | Always `true` when this call succeeds — a disabled/revoked key fails auth before reaching this endpoint.                         |
| `daily`                                 | `object \| undefined` | Present only if a daily cap is configured.                                                                                       |
| `weekly`                                | `object \| undefined` | Present only if a weekly cap is configured.                                                                                      |
| `monthly`                               | `object \| undefined` | Present only if a monthly cap is configured.                                                                                     |
| `total`                                 | `object \| undefined` | Present only if a lifetime cap is configured.                                                                                    |
| `daily.limit` / `.spent` / `.remaining` | `number`              | Cap, amount spent in the current window, and remaining capacity — all in credits. `remaining` is clamped to `0`, never negative. |

Every cap field (`daily`/`weekly`/`monthly`/`total`) shares the same `{ limit, spent, remaining }` shape. A key with no caps configured omits all four fields entirely.

#### Response Example

```json
{
	"name": "my-production-key",
	"isActive": true,
	"daily": { "limit": 100, "spent": 40, "remaining": 60 },
	"monthly": { "limit": 2000, "spent": 500, "remaining": 1500 }
}
```

### Reference: `usage` By Modality (From `generations`)

Based on current real records, the `usage` payload is modality-specific.

#### Text

Typical fields:

| Field                    | Type     |
| ------------------------ | -------- |
| `usage.promptTokens`     | `number` |
| `usage.completionTokens` | `number` |
| `usage.totalTokens`      | `number` |

#### Image

Typical fields:

| Field                   | Type     |
| ----------------------- | -------- |
| `usage.generatedImages` | `number` |
| `usage.inputTokens`     | `number` |
| `usage.outputTokens`    | `number` |
| `usage.totalTokens`     | `number` |

#### Video

Typical fields:

| Field                    | Type     |
| ------------------------ | -------- |
| `usage.completionTokens` | `number` |
| `usage.totalTokens`      | `number` |

The exact `usage` keys can vary by model and request type.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avis.xyz/api-reference/introduction/use.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.