> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 每日账单查询
> 按日期查询账单消费明细与日汇总数据，供对账、成本分析与账单采集使用
按日期查询账单的**消费明细**与**日汇总**数据，供客户侧对账、成本分析与账单采集使用。
## 接口信息
| 项目 | 说明 |
| ---- | ----------------------------------- |
| 服务域名 | `https://maas.gravitex.ai/prod-api` |
| 数据格式 | `application/json` |
| 字符编码 | `UTF-8` |
| 协议 | `HTTPS`（强制） |
| 金额币种 | `USD`（美元） |
| 计费时区 | `utc+8` |
### 接口清单
| 接口 | 请求地址 | 用途 |
| ---- | ------------------------------- | ------------------------------------- |
| 消费明细 | `GET /api/logs/getDailyList` | 按 `(账单日 × 账号 × 模型 × Token 类型)` 返回消费明细 |
| 日汇总 | `GET /api/logs/getDailySummary` | 按 `(账单日 × 账号)` 返回当日消费净额汇总 |
## 用户鉴权
所有请求必须在 HTTP Header 中携带 Bearer 凭证。**支持两种凭证，任选其一**：
| 凭证类型 | 说明 |
| ------------------------------------------------------------------ | ---------------------------- |
| [访问令牌（Access Token）](https://maas.gravitex.ai/#/profile?tab=token) | 平台为账号分配的访问令牌 |
| [API 密钥（API Key）](/cn/interface-module/token-management) | 平台为账号创建的 API 密钥，通常以 `sk-` 开头 |
格式 `Bearer <凭证>`，填入上述任一凭证即可
```http theme={null}
# 方式一：访问令牌
Authorization: Bearer
# 方式二：API 密钥
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
```
认证失败返回 HTTP `401`，业务码 `40100`。
不要在 URL、前端代码、日志或工单中明文记录完整 Key。
## 通用响应结构
所有接口返回统一结构：
```json theme={null}
{
"code": 0,
"message": "success",
"data": {
"total": 128,
"rows": []
}
}
```
| 字段 | 类型 | 说明 |
| ------------ | ------- | ------------------------- |
| `code` | integer | 业务状态码，`0` 表示成功，非 `0` 表示失败 |
| `message` | string | 提示信息 |
| `data` | object | 业务数据体；失败时为 `null` |
| `data.total` | integer | 满足查询条件的总条数（用于分页） |
| `data.rows` | array | 数据行列表 |
### 业务错误码
| code | HTTP 状态 | 说明 |
| ----- | ------- | ---------------------------------------- |
| 0 | 200 | 成功 |
| 40001 | 400 | 参数格式错误（日期格式非法、分页参数非正整数等） |
| 40002 | 400 | 缺少必填参数 |
| 40003 | 400 | 日期区间非法（`startDate` 晚于 `endDate`，或跨度超过上限） |
| 40100 | 401 | Token 缺失、无效或过期 |
| 50000 | 500 | 服务器内部错误 |
***
## 消费明细查询
```
GET https://maas.gravitex.ai/prod-api/api/logs/getDailyList
```
按 `(账单日 × 账号 × 模型 × Token 类型)` 返回消费明细。
### 查询参数
开始日期，格式 `yyyy-MM-dd`
结束日期，格式 `yyyy-MM-dd`；与 `startDate` 跨度不超过 **92 天**
账号 ID 筛选（多子账号可见需开通「企业管理」，详见[业务规则](#业务规则与约定)）；不传返回当前凭证可见的账号
账号名筛选，精确匹配（多子账号可见需开通「企业管理」，详见[业务规则](#业务规则与约定)）；不传返回当前凭证可见的账号
分页大小，正整数字符串；取值 `1 ~ 100`，超过 100 按 100 处理
当前页码，正整数字符串，从 `1` 开始
分页粒度为「消费明细条目」，`data.total` 为满足条件的明细总条数。
### 响应行字段（`data.rows[]`）
| 字段 | 类型 | 说明 |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `billMonth` | string | 账单月份，格式 `yyyyMM` |
| `billDay` | string | 账单日，格式 `yyyy-MM-dd` |
| `billingDateTimezone` | string | 计费时区，固定 `utc+8` |
| `account` | string | 账号名 |
| `modelType` | string | 模型分类，如 `claude`、`gpt`、`gemini`、`qwen`、`deepseek` 等 |
| `modelName` | string | 模型名称 |
| `tokenType` | string | Token 类型，枚举见下表 |
| `tokenCount` | string | 该类型消耗的 Token 数量（字符串型整数） |
| `tokenUnit` | string | Token 计量单位，固定 `million`（按每百万 Token 计价） |
| `currency` | string | 货币类型，固定 `USD` |
| `subtotalBeforeTax` | string | 折前税前金额（8 位小数） |
| `subtotalAfterDiscount` | string | 折后税前金额（8 位小数） |
| `totalAmountAfterTax` | string | 折后税后金额（8 位小数） |
| `price` | string | 单价：每 **1 个 `tokenUnit`（即每百万 Token）** 的折前单价（8 位小数）。换算关系：`subtotalBeforeTax = price × tokenCount ÷ 1,000,000`；`tokenCount` 为 0 时可能省略 |
| `entryType` | string | 条目类型，`normal` 表示正常消费 |
### `tokenType` 枚举
| 枚举值 | 说明 |
| ----------------------- | -------------------- |
| `textInputTokens` | 文本输入 Token |
| `textOutputTokens` | 文本输出 Token |
| `reasoningTokens` | 推理/思考 Token |
| `cacheCreationTokens5m` | 缓存创建 Token（5 分钟 TTL） |
| `cacheCreationTokens1h` | 缓存创建 Token（1 小时 TTL） |
| `cacheTokens` | 缓存命中（读取）Token |
| `imageInputTokens` | 图片输入 Token |
| `imageOutputTokens` | 图片输出 Token |
| `audioInputTokens` | 音频输入 Token |
| `audioOutputTokens` | 音频输出 Token |
| `videoInputTokens` | 视频输入 Token |
| `videoOutputTokens` | 视频输出 Token |
排序规则：`billDay` 降序，其次 `account`、`modelName`、`tokenType`、`currency` 升序。
### 请求示例
```bash theme={null}
curl "https://maas.gravitex.ai/prod-api/api/logs/getDailyList?startDate=2026-07-27&endDate=2026-07-27&pageSize=100&pageNum=1" \
-H "Authorization: Bearer "
```
### 响应示例
```json theme={null}
{
"code": 0,
"message": "success",
"data": {
"total": 23,
"rows": [
{
"billMonth": "202607",
"billDay": "2026-07-27",
"billingDateTimezone": "utc+8",
"account": "your_account",
"modelType": "claude",
"modelName": "claude-opus-4-8",
"tokenType": "textOutputTokens",
"tokenCount": "2931",
"tokenUnit": "million",
"currency": "USD",
"subtotalBeforeTax": "0.07327564",
"subtotalAfterDiscount": "0.07327564",
"totalAmountAfterTax": "0.07327564",
"price": "25.00021836",
"entryType": "normal"
}
]
}
}
```
***
## 日汇总查询
```
GET https://maas.gravitex.ai/prod-api/api/logs/getDailySummary
```
返回按天粒度的消费净额汇总，响应体较明细接口轻量，适用于账单概览、日趋势、月度报表等场景。
### 查询参数
开始日期，格式 `yyyy-MM-dd`
结束日期，格式 `yyyy-MM-dd`；与 `startDate` 跨度不超过 **366 天**
账号 ID 筛选（多子账号可见需开通「企业管理」，详见[业务规则](#业务规则与约定)）；不传返回当前凭证可见的账号
账号名筛选，精确匹配（多子账号可见需开通「企业管理」，详见[业务规则](#业务规则与约定)）；不传返回当前凭证可见的账号
分页大小，正整数字符串；取值 `1 ~ 400`，超过 400 按 400 处理
当前页码，正整数字符串，从 `1` 开始
分页粒度为「账单日 × 账号」，`data.total` 为满足条件的组合总数。
### 响应行字段（`data.rows[]`）
| 字段 | 类型 | 说明 |
| ----------------------- | ------ | ------------------- |
| `billMonth` | string | 账单月份，格式 `yyyyMM` |
| `billDay` | string | 账单日，格式 `yyyy-MM-dd` |
| `billingDateTimezone` | string | 计费时区，固定 `utc+8` |
| `account` | string | 账号名 |
| `currency` | string | 货币类型，固定 `USD` |
| `subtotalBeforeTax` | string | 当日折前税前净额（8 位小数） |
| `subtotalAfterDiscount` | string | 当日折后税前净额（8 位小数） |
| `totalAmountAfterTax` | string | 当日折后税后净额（8 位小数） |
排序规则：`billDay` 降序，其次 `account` 升序。
### 请求示例
```bash theme={null}
curl "https://maas.gravitex.ai/prod-api/api/logs/getDailySummary?startDate=2026-07-01&endDate=2026-07-27&pageSize=31&pageNum=1" \
-H "Authorization: Bearer "
```
### 响应示例
```json theme={null}
{
"code": 0,
"message": "success",
"data": {
"total": 2,
"rows": [
{
"billMonth": "202607",
"billDay": "2026-07-27",
"billingDateTimezone": "utc+8",
"account": "your_account",
"currency": "USD",
"subtotalBeforeTax": "0.26569400",
"subtotalAfterDiscount": "0.26569400",
"totalAmountAfterTax": "0.26569400"
}
]
}
}
```
***
## 业务规则与约定
1. **金额精度**：所有金额字段以 `string` 传输，保留 8 位小数，避免 JSON number 精度丢失。
2. **金额一致性**：同一账单日、同一账号下，日汇总的各金额字段等于该日消费明细对应金额字段之和（跨页累加）。
3. **零消费日**：查询区间内无消费的日期不返回记录。
4. **数据延迟**：账单数据为 T+1，即最新一天的数据在次日可查询。
5. **账号范围与企业管理**：默认情况下，凭证只能查询**自身账号**的账单数据。若该账号已开通「**企业管理**」并作为主账号，则可见其名下**全部子账号**的账单——此时不传 `userId`/`userName` 返回全部子账号，传入则筛选到指定子账号（子账号自身的凭证仅能查询自己）。**开通企业管理请联系平台管理员。**
6. **分页越界**：当 `pageNum` 超过总页数时，返回空 `rows`，`total` 仍为真实总数。