# List request logs

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

List the current user’s model calls, token usage, and billing reporting results.

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

## Before you begin

Prepare a personal access token. For creation and management, see [Manage personal access tokens](../../../../../guides/billing/credentials.md#personal-access-token).

Results are scoped to data accessible to the current user.

## Query parameters

Replace `$MOI_PERSONAL_ACCESS_TOKEN` in the example with your personal access token.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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"
```

Save the returned `next_page_token` as `$NEXT_PAGE_TOKEN`, retain the same filters, and request the next page. Stop when this value is empty or omitted.

```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} Parameters

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `start_time` | integer | No | Start time in nonnegative Unix seconds; must not exceed `end_time`. |
| `end_time` | integer | No | End time in nonnegative Unix seconds. |
| `model_id` | string | No | Catalog model object ID. |
| `model_type` | string | No | Model type. |
| `requested_model` | string | No | Model name submitted in the inference request. |
| `status` | string | No | Call status, such as `success` or `failed`. |
| `error_type` | string | No | Call error category. |
| `caller_ip` | string | No | Caller IP address. |
| `token_key_id` | string | No | TaaS local token key ID. |
| `token_key_ids` | string | No | TaaS local key IDs; repeat the parameter or comma-separate values. |
| `credential_type` | string | Required with `credential_id` | Credential type: `taas_token_key`, `personal_access_token`, or `service_account_api_key`; requires `credential_id`. |
| `credential_id` | string | Required with `credential_type` | Credential object ID; requires `credential_type`. |
| `billing_event_id` | string | No | Billing usage-event ID. |
| `billing_record_id` | string | No | Billing record ID. |
| `pricing_mode` | string | No | Pricing mode. |
| `settlement_method` | string | No | Settlement method: genesis or `ai_service`. |
| `enterprise_plan_id` | string | No | Enterprise plan ID. |
| `enterprise_contract_no` | string | No | Enterprise contract number. |
| `enterprise_plan_model_id` | string | No | Enterprise plan model ID. |
| `response_id` | string | No | Responses response ID. |
| `conversation_id` | string | No | Conversation ID. |
| `ids` | string | No | Usage log IDs; repeat the parameter or comma-separate values. |
| `usage_ids` | string | No | Alias for ids; values are combined. |
| `provider_id` | string | No | Provider ID; results remain scoped to the current user. |
| `page_size` | integer | No | Page size; default 100, maximum 1000. |
| `page_token` | string | No | Next-page token from the previous response; omit for the first request. |

::::

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

## Successful response

Returns HTTP `200` with the current page of request logs and pagination information.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| `items` | array of object | Records on this page. |
| `items[].id` | string | Usage log ID. |
| `items[].token_key_id` | string | TaaS local key ID, for calls using that credential type. |
| `items[].token_key_name` | string | TaaS local key name. |
| `items[].user_id` | string | Calling user ID. |
| `items[].user_name` | string | Calling user name, when available. |
| `items[].model_id` | string | Catalog model object ID. |
| `items[].model_name` | string | Actual model name. |
| `items[].requested_model` | string | Model name submitted in the request. |
| `items[].caller_ip` | string | Caller IP. |
| `items[].called_at` | integer | Call time, Unix seconds. |
| `items[].input_tokens` | integer | Input tokens. |
| `items[].output_tokens` | integer | Output tokens. |
| `items[].cache_read_tokens` | integer | Cache-read tokens. |
| `items[].cache_creation_tokens` | integer | Cache-creation tokens. |
| `items[].cost` | string | Call cost as a decimal string. |
| `items[].status` | string | Call result status. |
| `items[].error_type` | string | Call error category, when present. |
| `items[].error_message` | string | Call error description, when present. |
| `items[].latency_ms` | integer | Call `latency` in milliseconds. |
| `items[].request_body_ref_id` | string | Archive reference ID for the request body. Returned when populated. |
| `items[].response_body_ref_id` | string | Archive reference ID for the response body. Returned when populated. |
| `items[].request_body_sha256` | string | SHA-256 of the full request body. Returned when populated. |
| `items[].response_body_sha256` | string | SHA-256 of the full response body. Returned when populated. |
| `items[].request_id` | string | Request tracing ID. Returned when populated. |
| `items[].key_hash_prefix` | string | Key-hash prefix. Returned when populated. |
| `items[].meter_code` | string | Billing meter code. Returned when populated. |
| `items[].pricing_mode` | string | Call pricing mode. Returned when populated. |
| `items[].enterprise_plan_id` | string | Enterprise plan ID. Returned when populated. |
| `items[].enterprise_plan_name` | string | Enterprise plan name. Returned when populated. |
| `items[].enterprise_contract_no` | string | Enterprise contract number. Returned when populated. |
| `items[].enterprise_plan_model_id` | string | Enterprise plan model ID. Returned when populated. |
| `items[].pricing_snapshot` | string | Serialized pricing snapshot. Returned when populated. |
| `items[].settlement_method` | string | Settlement method. Returned when populated. |
| `items[].billing_report_status` | string | Usage reporting status. Returned when populated. |
| `items[].billing_report_group_id` | string | Usage reporting group ID. Returned when populated. |
| `items[].billing_event_key` | string | Idempotency key for the billing usage event. Returned when populated. |
| `items[].billing_event_id` | string | Billing usage-event ID. Returned when populated. |
| `items[].billing_record_id` | string | Billing record ID. Returned when populated. |
| `items[].billing_account_id` | string | Billing account ID. Returned when populated. |
| `items[].billing_rated_credit` | string | Credit amount rated for this call. Returned when populated. |
| `items[].billing_credit_balance` | string | Credit balance recorded from the reporting result. Returned when populated. |
| `items[].billing_credit_available` | string | Available credit recorded from the reporting result. Returned when populated. |
| `items[].billing_last_error` | string | Latest billing usage-reporting error. Returned when populated. |
| `items[].request_body_bytes` | integer | Full request body size in bytes. |
| `items[].response_body_bytes` | integer | Full response body size in bytes. |
| `items[].billing_reported_at` | integer | Billing reporting time, Unix seconds, when present. |
| `items[].billing_report_attempts` | integer | Billing reporting attempts. |
| `items[].created_at` | integer | Log creation time, Unix seconds. |
| `items[].credential` | object | Credential identity for this call, when recorded. |
| `items[].credential.type` | string | Credential type: `taas_token_key`, `personal_access_token`, or `service_account_api_key`. |
| `items[].credential.id` | string | Credential object ID. |
| `items[].credential.service_account_id` | string | Service account ID; returned for service-account credentials. |
| `total` | integer | Total records matching the filters. |
| `next_page_token` | string | Next-page token; empty or omitted on the last page. |

In field paths, `[]` denotes each array item.

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

## Error response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | HTTP error status. |
| `message` | string | Error description. |

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

## Next steps

Use an item’s id to [Get request log details](get-request-log.md).