# 查询请求日志列表

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

查询当前用户的模型调用记录、Token 用量和计费上报结果。

```text
GET https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs
```

## 调用前准备

准备个人访问令牌。创建和管理方法参阅[创建和管理个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)。

查询范围为当前用户有权访问的数据。

## 查询参数

将示例中的 `$MOI_PERSONAL_ACCESS_TOKEN` 替换为个人访问令牌。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "page_size=2"
```

将响应中的 `next_page_token` 保存为 `$NEXT_PAGE_TOKEN`，保持筛选条件不变并请求下一页。该值为空或省略时停止翻页。

```bash
curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "page_size=2" \
  --data-urlencode "page_token=$NEXT_PAGE_TOKEN"
```

:::::
:::::{tab-item} 参数说明

::::{div} mo-api-parameter-table

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `start_time` | integer | 否 | 开始时间，非负 Unix 秒；不能晚于结束时间。 |
| `end_time` | integer | 否 | 结束时间，非负 Unix 秒。 |
| `model_id` | string | 否 | 模型目录对象 ID。 |
| `model_type` | string | 否 | 模型类型。 |
| `requested_model` | string | 否 | 调用请求填写的模型名称。 |
| `status` | string | 否 | 调用状态，例如 `success` 或 `failed`。 |
| `error_type` | string | 否 | 调用错误类别。 |
| `caller_ip` | string | 否 | 调用方 IP。 |
| `token_key_id` | string | 否 | TaaS 本地密钥 ID。 |
| `token_key_ids` | string | 否 | TaaS 本地密钥 ID 列表；可重复传递或用逗号分隔。 |
| `credential_type` | string | 填写 `credential_id` 时必填 | 凭据类别：`taas_token_key`、`personal_access_token` 或 `service_account_api_key`；必须同时填写 `credential_id`。 |
| `credential_id` | string | 填写 `credential_type` 时必填 | 凭据对象 ID；必须同时填写 `credential_type`。 |
| `billing_event_id` | string | 否 | 计费用量事件 ID。 |
| `billing_record_id` | string | 否 | 计费记录 ID。 |
| `pricing_mode` | string | 否 | 计价方式。 |
| `settlement_method` | string | 否 | 结算方式：genesis 或 `ai_service`。 |
| `enterprise_plan_id` | string | 否 | 企业方案 ID。 |
| `enterprise_contract_no` | string | 否 | 企业合同编号。 |
| `enterprise_plan_model_id` | string | 否 | 企业方案模型 ID。 |
| `response_id` | string | 否 | Responses 响应 ID。 |
| `conversation_id` | string | 否 | Conversation ID。 |
| `ids` | string | 否 | 请求日志 ID 列表；可重复传递或用逗号分隔。 |
| `usage_ids` | string | 否 | ids 的兼容参数；与 ids 合并。 |
| `provider_id` | string | 否 | 供应商 ID；查询仍限定为当前用户的调用。 |
| `page_size` | integer | 否 | 每页数量，默认 100，最大 1000。 |
| `page_token` | string | 否 | 上一页返回的下一页标记；首个请求省略。 |

::::

:::::
::::::
:::::::

## 成功响应

返回 HTTP `200`，响应包含当前页的请求日志及分页信息。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "items": [
    {
      "id": "usage_example",
      "user_id": "user_example",
      "model_id": "model_example",
      "model_name": "example-chat-model",
      "requested_model": "example-chat-model",
      "called_at": 1788710400,
      "input_tokens": 12,
      "output_tokens": 8,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "cost": "0.0001",
      "status": "success",
      "latency_ms": 120,
      "request_body_ref_id": "body_request_example",
      "response_body_ref_id": "body_response_example",
      "request_body_sha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "response_body_sha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "request_body_bytes": 2,
      "response_body_bytes": 2,
      "created_at": 1788710400,
      "credential": {
        "type": "personal_access_token",
        "id": "credential_example"
      }
    }
  ],
  "total": 1,
  "next_page_token": ""
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items` | array of object | 本页记录。 |
| `items[].id` | string | 请求日志 ID。 |
| `items[].token_key_id` | string | TaaS 本地密钥 ID；使用该类密钥时返回。 |
| `items[].token_key_name` | string | TaaS 本地密钥名称。 |
| `items[].user_id` | string | 调用用户 ID。 |
| `items[].user_name` | string | 调用用户名称；有值时返回。 |
| `items[].model_id` | string | 模型目录对象 ID。 |
| `items[].model_name` | string | 实际调用的模型名称。 |
| `items[].requested_model` | string | 请求填写的模型名称。 |
| `items[].caller_ip` | string | 调用方 IP。 |
| `items[].called_at` | integer | 调用时间，Unix 秒。 |
| `items[].input_tokens` | integer | 输入 Token 数。 |
| `items[].output_tokens` | integer | 输出 Token 数。 |
| `items[].cache_read_tokens` | integer | 缓存读取 Token 数。 |
| `items[].cache_creation_tokens` | integer | 缓存写入 Token 数。 |
| `items[].cost` | string | 本次调用费用，十进制字符串。 |
| `items[].status` | string | 调用结果状态。 |
| `items[].error_type` | string | 调用错误类别；有错误时返回。 |
| `items[].error_message` | string | 调用错误说明；有错误时返回。 |
| `items[].latency_ms` | integer | 调用耗时，毫秒。 |
| `items[].request_body_ref_id` | string | 请求正文的归档引用 ID。 有值时返回。 |
| `items[].response_body_ref_id` | string | 响应正文的归档引用 ID。 有值时返回。 |
| `items[].request_body_sha256` | string | 完整请求正文的 SHA-256。 有值时返回。 |
| `items[].response_body_sha256` | string | 完整响应正文的 SHA-256。 有值时返回。 |
| `items[].request_id` | string | 请求追踪 ID。 有值时返回。 |
| `items[].key_hash_prefix` | string | 密钥哈希前缀。 有值时返回。 |
| `items[].meter_code` | string | 计费项代码。 有值时返回。 |
| `items[].pricing_mode` | string | 调用计价方式。 有值时返回。 |
| `items[].enterprise_plan_id` | string | 企业方案 ID。 有值时返回。 |
| `items[].enterprise_plan_name` | string | 企业方案名称。 有值时返回。 |
| `items[].enterprise_contract_no` | string | 企业合同编号。 有值时返回。 |
| `items[].enterprise_plan_model_id` | string | 企业方案模型 ID。 有值时返回。 |
| `items[].pricing_snapshot` | string | 计价快照，序列化字符串。 有值时返回。 |
| `items[].settlement_method` | string | 结算方式。 有值时返回。 |
| `items[].billing_report_status` | string | 用量上报状态。 有值时返回。 |
| `items[].billing_report_group_id` | string | 用量上报批次 ID。 有值时返回。 |
| `items[].billing_event_key` | string | 计费用量事件的幂等标识。 有值时返回。 |
| `items[].billing_event_id` | string | 计费用量事件 ID。 有值时返回。 |
| `items[].billing_record_id` | string | 计费记录 ID。 有值时返回。 |
| `items[].billing_account_id` | string | 计费账户 ID。 有值时返回。 |
| `items[].billing_rated_credit` | string | 本次计费的 Credit 数量。 有值时返回。 |
| `items[].billing_credit_balance` | string | 上报结果记录的 Credit 余额。 有值时返回。 |
| `items[].billing_credit_available` | string | 上报结果记录的可用 Credit。 有值时返回。 |
| `items[].billing_last_error` | string | 最近一次计费用量上报错误。 有值时返回。 |
| `items[].request_body_bytes` | integer | 完整请求正文的字节数。 |
| `items[].response_body_bytes` | integer | 完整响应正文的字节数。 |
| `items[].billing_reported_at` | integer | 计费用量上报时间，Unix 秒；有值时返回。 |
| `items[].billing_report_attempts` | integer | 计费用量上报尝试次数。 |
| `items[].created_at` | integer | 日志创建时间，Unix 秒。 |
| `items[].credential` | object | 本次调用的凭据标识；有记录时返回。 |
| `items[].credential.type` | string | 凭据类别：`taas_token_key`、`personal_access_token` 或 `service_account_api_key`。 |
| `items[].credential.id` | string | 凭据对象 ID。 |
| `items[].credential.service_account_id` | string | 服务账号 ID；仅服务账号凭据返回。 |
| `total` | integer | 符合筛选条件的总记录数。 |
| `next_page_token` | string | 下一页标记；为空或省略时已到最后一页。 |

字段路径中的 `[]` 表示数组中的每一项。

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 400,
  "message": "page_size must be an integer between 1 and 1000"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | HTTP 错误状态码。 |
| `message` | string | 错误说明。 |

:::::
::::::
:::::::

## 后续操作

使用 `items[].id` [查询请求日志详情](get-request-log.md)。