# Get usage trends

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

Get the current user’s call, token, and cost metrics over time.

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

## 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/trend" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "granularity=day"
```

:::::
:::::{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. |
| `granularity` | string | No | Bucket granularity: `hour` or `day`; defaults to `hour`. |

::::

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

## Successful response

Returns HTTP `200` with call statistics grouped into time buckets.

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

```json
{
  "points": [
    {
      "timestamp": 1788710400,
      "time": "2026-09-07T00:00:00Z",
      "calls": 2,
      "total_calls": 2,
      "input_tokens": 12,
      "output_tokens": 8,
      "total_input_tokens": 12,
      "total_output_tokens": 8,
      "total_user_tokens": 20,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "total_cost": "0.0001",
      "total_channel_cost": "0.00005",
      "total_channel_tokens": 20,
      "total_cache_read_tokens": 0,
      "total_cache_creation_tokens": 0
    }
  ],
  "granularity": "day",
  "start_time": 1788710400,
  "end_time": 1788796799,
  "truncated": false
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `points` | array of object | Buckets with data, ordered by time; empty buckets are not filled. |
| `points[].timestamp` | integer | Bucket start in Unix seconds. |
| `points[].time` | string | Bucket start in UTC, RFC 3339 format. |
| `points[].calls` | integer | Call count in this bucket. |
| `points[].total_calls` | integer | Alias of calls. |
| `points[].input_tokens` | integer | Input tokens. |
| `points[].output_tokens` | integer | Output tokens. |
| `points[].total_input_tokens` | integer | Alias of `input_tokens`. |
| `points[].total_output_tokens` | integer | Alias of `output_tokens`. |
| `points[].total_user_tokens` | integer | Sum of input, output, cache-read, and cache-creation tokens. |
| `points[].cache_read_tokens` | integer | Total cache-read tokens. |
| `points[].cache_creation_tokens` | integer | Total cache-creation tokens. |
| `points[].total_cost` | string | Total call cost as a decimal string. |
| `points[].total_channel_cost` | string | Total cost of associated upstream requests. |
| `points[].total_channel_tokens` | integer | Input, output, and cache tokens across associated upstream requests. |
| `points[].total_cache_read_tokens` | integer | Alias of `cache_read_tokens`. |
| `points[].total_cache_creation_tokens` | integer | Alias of `cache_creation_tokens`. |
| `granularity` | string | Requested bucket granularity. |
| `start_time` | integer | Effective range start, Unix seconds. |
| `end_time` | integer | Effective range end, Unix seconds. |
| `truncated` | boolean | True when an omitted start or a range exceeding 999 intervals shortens the range. |

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

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

An omitted or future end time is limited to the current time. When the range exceeds the limit, the most recent interval is retained.

## Error response

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

```json
{
  "code": 400,
  "message": "start_time must be a non-negative unix timestamp"
}
```

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

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

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