# kindgi usage

> Your tenant's usage, aggregated, over the projects you may read: a month's (or a window's) counts and sums by project, agent, kind, class, state or day

## `kindgi usage`

**Synopsis**

```sh signature
kindgi usage [--month=<YYYY-MM> | --from=<time> --to=<time>] [--project=<id>] [--group-by=<keys>] [--kind=<kinds>] [--class=<classes>] [--state=<states>] [--limit=<n>] [--cursor=<c>]
```

Your tenant's usage, aggregated, over the projects you may read: a month's (or a window's) counts and sums by project, agent, kind, class, state or day.

**Options**

| Option               | Default                                                                | Description                                                                                  |
| -------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `--class <value>`    | none: every run class                                                  | Only these run classes, comma-separated (production, staging, dry-run, replay, eval, child). |
| `--cursor <value>`   | none: the first page                                                   | The previous page's `nextCursor`, from the same query.                                       |
| `--from <value>`     | none; with `--to` it sets a window instead of a month                  | The window's start: a time with a zone, or a date (UTC). With --to.                          |
| `--group-by <value>` | `project,kind`                                                         | Comma-separated, from project, agent, kind, class, state, day (default project,kind).        |
| `--kind <value>`     | none: every kind                                                       | Only these kinds, comma-separated (run.started, run.ended, llm.inference, …).                |
| `--limit <value>`    | `1000` (`1` to `10000`)                                                | Groups a page: 1 to 10000 (default 1000).                                                    |
| `--month <value>`    | the current calendar month, in UTC                                     | A calendar month in UTC, YYYY-MM (default: the current one).                                 |
| `--project <value>`  | none: every project you can read                                       | Only this project's usage. One you can't read gives no groups.                               |
| `--state <value>`    | none: every state                                                      | Only these states, comma-separated (completed, failed, approved, on, …).                     |
| `--to <value>`       | none; the window ends here (exclusive), at most 92 days after `--from` | The window's end, not included; at most 92 days after --from.                                |

Every command also takes the [global flags](https://docs.kindgi.com/reference/cli.md#global-flags).

**Examples**

This month's usage so far, grouped by project and kind (the default).

```sh
kindgi usage
```

A past month, broken down by agent and kind, as a table.

```sh
kindgi usage --month=2026-09 --group-by=agent,kind --table
```

**See also**

- [Cost per run and per customer](https://docs.kindgi.com/guides/observability/cost-per-run.md)
- [Organize work by org and project](https://docs.kindgi.com/guides/projects/organize-by-org-and-project.md)