---
title: usage
description: Inspect usage over a time range.
canonical_url: https://orchestor.io/docs/en/cli/usage
markdown_url: https://orchestor.io/docs/en/cli/usage.md
contentType: reference
---

# usage

`orc usage get` retrieves usage records aggregated into time buckets for the target Workspace. Group by model, API key ID, or endpoint group, and filter by API key IDs.

`--start-time` is a required inclusive RFC 3339 timestamp. `--end-time` is exclusive and must follow the start. The range cannot exceed 90 days. When omitted, the end defaults to the current time of each request; supply it explicitly to keep the range fixed while paging.

## Usage

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

*Retrieve a fixed interval.*

## Aggregation and pagination

Omitting grouping aggregates matching records within each bucket. Group fields whose stored value is null are omitted from results. Pass returned `--cursor` values unchanged, retaining the range, filters, and grouping.

## Subcommands

### `get`

`--bucket-width` accepts `1h` or `1d`, defaulting to `1d`. Separate `model`, `api_key_id`, and `endpoint_group` values with commas for `--group-by`. `--api-key-ids` takes identifiers, never secret key values.

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

#### Unique 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.

Type: `string`. Required.

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

Type: `string`. Optional.

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

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

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

## Examples

### Retrieve JSON by model.

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

*Retrieve JSON by model.*

## Permissions

Authenticate and select the target Workspace. Access to that Workspace is required.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc usage`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--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#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

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