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

# Query API Key Billing

## Request Headers

**Content-Type** `string` *required*

Enum: `application/json`

**Authorization** `string` *required*

Bearer authentication format, for example: Bearer \{\{API Key}}.

## Query Parameters

**cycleType** `string` *required*

Billing granularity. The maximum query range depends on the granularity you pick:

* `Hour` (up to 7 days per request)
* `Day` (up to 31 days per request)
* `Week` (up to 31 days per request)
* `Month` (up to 31 days per request)

**category** `string`

Product type or business category. Common values: `llm`, `gen_api`, `web_search`.

**productName** `string`

Product name. Supports fuzzy matching.

**startTime** `integer` *required*

Query start time, Unix timestamp in seconds (int64). Must be greater than or equal to `2026-01-01 00:00:00`.

**endTime** `integer` *required*

Query end time, Unix timestamp in seconds (int64). Must be greater than `startTime`.

> [!NOTE]
>
> This endpoint only supports data after `2026-01-01 00:00:00`. It does not support pagination. The range between `startTime` and `endTime` must stay within the limit for the `cycleType` you request: 7 days for `Hour`, 31 days for `Day`, `Week`, and `Month`. To cover a longer period, split it into several requests.

> [!WARNING]
>
> **The query range limit is now enforced by the API.** It used to be applied only in the Novita console, so requests sent directly to this endpoint were never rejected for being too long. If your integration queries more than 31 days at once (or more than 7 days with `cycleType=Hour`), it now fails with HTTP `400` and a message in the form:
>
> ```text theme={"system"}
> time range must not exceed 31 days for cycleType "Month"
> ```
>
> The message always names the limit and the granularity that was rejected, so you can split the range and retry.

> [!NOTE]
>
> The API Key billing page in the Novita console offers only hourly and daily granularity. This endpoint still accepts all four values, so `Week` and `Month` remain available to API callers even though they are no longer offered in the console.

## Response Parameters

**bills** `object[]` *required*

API Key bill list.

**properties**

**userId** `string` *required*

User account ID.

**startTime** `string` *required*

Bill start time, Unix timestamp in seconds. It marks the first second of the billing period. With `cycleType=Hour`, it is the top of that hour, for example `10:00:00`.

**endTime** `string` *required*

Bill end time, Unix timestamp in seconds. It marks the last second of the billing period. With `cycleType=Hour`, it is minute `59` and second `59` of the same hour, for example `10:59:59`.

**billingMethod** `int32` *required*

Billing method: `1` (pay-as-you-go), `2` (subscription).

**productName** `string` *required*

Product name.

**category** `string` *required*

Product type or subcategory.

**ownerID** `string` *required*

API Key ID.

**apikeyName** `string` *required*

API Key name.

**apikeyMask** `string` *required*

Masked API Key.

**productId** `string` *required*

Product ID.

**billNum0** `string` *required*

Usage field 0. For `llm`, this usually means input price per 1M tokens; GPU: price per card per hour; storage: price per GB per day.

**billNum1** `string` *required*

Usage field 1. For `llm`, this usually means output tokens.

**billNum2** `string` *required*

Usage field 2. For `llm`, this usually means read cache price per 1M tokens.

**billNum3** `string` *required*

Usage field 3. For `llm`, this usually means write 5-minute cache price per 1M tokens.

**billNum4** `string` *required*

Usage field 4. For `llm`, this usually means reasoning token price per 1M tokens.

**billNum5** `string` *required*

Usage field 5. For `llm`, this usually means write 1-hour cache price per 1M tokens.

**billNum6** `string`

Usage field 6.

**billNum7** `string`

Usage field 7.

**billNum8** `string`

Usage field 8.

**billNum9** `string`

Usage field 9.

**billNum10** `string`

Usage field 10.

**billNum11** `string`

Usage field 11.

**billNum12** `string`

Usage field 12.

**billNum13** `string`

Usage field 13.

**billNum14** `string`

Usage field 14.

**billNum15** `string`

Usage field 15.

**basePrice0** `string` *required*

Original price field 0. For `llm`: input price per 1M tokens; GPU: price per card per hour; storage: price per GB per day.

**basePrice1** `string` *required*

Original price field 1. For `llm`, output price per 1M tokens.

**basePrice2** `string` *required*

Original price field 2. For `llm`, read cache price per 1M tokens.

**basePrice3** `string` *required*

Original price field 3. For `llm`, write 5-minute cache price per 1M tokens.

**basePrice4** `string` *required*

Original price field 4. For `llm`, reasoning token price per 1M tokens.

**basePrice5** `string` *required*

Original price field 5. For `llm`, write 1-hour cache price per 1M tokens.

**discountPrice0** `string` *required*

Discounted price field 0. For `llm`, discounted input token price.

**discountPrice1** `string` *required*

Discounted price field 1. For `llm`, discounted output token price.

**discountPrice2** `string` *required*

Discounted price field 2. For `llm`, discounted read cache price per 1M tokens.

**discountPrice3** `string` *required*

Discounted price field 3. For `llm`, discounted write 5-minute cache price per 1M tokens.

**discountPrice4** `string` *required*

Discounted price field 4. For `llm`, discounted reasoning token price per 1M tokens.

**discountPrice5** `string` *required*

Discounted price field 5. For `llm`, discounted write 1-hour cache price per 1M tokens.

**amount** `string` *required*

Total amount, unit is 1/10000 USD.

**voucherAmount** `string` *required*

Amount deducted by vouchers, unit is 1/10000 USD.

**payAmount** `string` *required*

Cash payment amount, unit is 1/10000 USD.

**payAmountDisplay** `float` *required*

Display value of cash payment amount, in USD.

**pricePrecision** `int32` *required*

Price precision. Unit price (USD) = unit price / 10000 / `pricePrecision`.

**llmSeries** `string`

LLM series.

**requestCount** `string`

Request count.

**multimodalPricing** `object`

Multimodal model billing details.

**tieredConfig** `object`

Tiered billing configuration.

```bash Daily granularity theme={"system"}
curl --request GET \
  --url 'https://api.novita.ai/openapi/v1/billing/apikey/bill/list?cycleType=Day&category=llm&startTime=1767225600&endTime=1769817599' \
  --header 'Authorization: Bearer <API_KEY>'
```

```bash Hourly granularity theme={"system"}
curl --request GET \
  --url 'https://api.novita.ai/openapi/v1/billing/apikey/bill/list?cycleType=Hour&category=llm&startTime=1767225600&endTime=1767830399' \
  --header 'Authorization: Bearer <API_KEY>'
```

```json 200 theme={"system"}
{
  "bills": [
    {
      "userId": "<string>",
      "startTime": "1767225600",
      "endTime": "1767311999",
      "billingMethod": 1,
      "productName": "<string>",
      "category": "llm",
      "ownerID": "<api_key_id>",
      "billNum0": "1000",
      "billNum1": "500",
      "basePrice0": "0",
      "basePrice1": "0",
      "discountPrice0": "0",
      "discountPrice1": "0",
      "amount": "10000",
      "voucherAmount": "0",
      "payAmount": "10000",
      "payAmountDisplay": 1,
      "pricePrecision": 1,
      "productId": "<string>",
      "apikeyName": "<string>",
      "apikeyMask": "sk-****"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.