---
title: usage
description: 時間範囲の利用量を確認する。
canonical_url: https://orchestor.io/docs/cli/usage
markdown_url: https://orchestor.io/docs/cli/usage.md
contentType: reference
---

# usage

`orc usage get` は、対象Workspaceの利用記録を時間bucketで集計します。モデル、API key ID、endpoint groupで分け、API key IDで対象を絞り込めます。

`--start-time` は必須のRFC 3339日時で、その時刻を含みます。`--end-time` は含まない上限で、開始より後を指定します。範囲は最大90日です。終了を省略すると各requestの現在時刻を使うため、ページ送りでは終了を明示して範囲を固定します。

## 使い方

```bash title="terminal"
orc usage get --start-time 2026-09-01T00:00:00Z --end-time 2026-10-01T00:00:00Z
```

*期間を固定して取得します。*

## 集計とページ送り

group化を省略すると各bucket内の該当記録を集計します。保存された値がnullのgroup項目は結果から省略されます。`--cursor` は返された値を変更せず使い、範囲・filter・group条件を維持します。

## サブコマンド

### `get`

`--bucket-width` は `1h` または `1d` で、既定値は `1d` です。`--group-by` は `model`、`api_key_id`、`endpoint_group` をカンマで区切ります。`--api-key-ids` は識別子を指定し、秘密のkey値を渡しません。

```bash title="terminal"
orc usage get [options]
```

#### 固有のオプション

##### `--start-time`

Inclusive lower bound for usage records, as an RFC 3339 timestamp. Required. The range from start_time to end_time cannot exceed 90 days.

型: `string`。必須。

```bash title="terminal"
orc usage get --start-time <value>
```

##### `--end-time`

Exclusive upper bound for usage records. Must be after start_time. Defaults to the time of each request; set it explicitly to keep a fixed range across pages.

型: `string`。任意。

```bash title="terminal"
orc usage get --end-time <value>
```

##### `--bucket-width`

Time bucket width. Defaults to 1d.; enum: 1h|1d

型: `string`。任意。

```bash title="terminal"
orc usage get --bucket-width <value>
```

##### `--group-by`

Split each time bucket by one or more selected dimensions. Omit to aggregate all matching records in each bucket. Use repeated HTTP query parameters, for example group_by=model&group_by=endpoint_group. A grouping field is omitted from a result when its stored value is null.; csv of: model|api_key_id|endpoint_group

型: `string`。任意。

```bash title="terminal"
orc usage get --group-by <value>
```

##### `--api-key-ids`

Include records attributed to any of these API key IDs. Omit for all keys in the workspace. Use repeated parameters, such as api_key_ids=key_a&api_key_ids=key_b; pass identifiers, never secret key values.; csv

型: `string`。任意。

```bash title="terminal"
orc usage get --api-key-ids <value>
```

## 使用例

### モデルごとのJSONを取得します。

```bash title="terminal"
orc usage get --start-time 2026-09-01T00:00:00Z --end-time 2026-10-01T00:00:00Z --group-by model --json
```

*モデルごとのJSONを取得します。*

## 必要な権限

認証し、対象Workspaceを選択して実行します。対象Workspaceへのアクセスが必要です。

## グローバルオプション

`orc usage` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5)
- [`--limit`](https://orchestor.io/docs/cli/global-flags.md)
- [`--cursor`](https://orchestor.io/docs/cli/global-flags.md)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E5%8F%96%E5%BE%97)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#%E8%AA%AD%E3%81%BF%E5%8F%96%E3%82%8A%E5%B0%82%E7%94%A8%E3%83%A2%E3%83%BC%E3%83%89)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#%E5%A4%96%E9%83%A8%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%81%AE%E7%9B%AE%E5%8D%B0%E4%BB%98%E3%81%91)

各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。

---

[Documentation index](https://orchestor.io/docs/llms.txt)