---
layout: docs
page_title: operator usage - Command
description: |-
  "operator usage" produces a report on active clients.
---

# operator usage

The `operator usage` command allows an administrator to retrieve a
[client count](https://www.vaultproject.io/docs/concepts/client-count) report
for the default reporting period, or for a specific time range of months.

The command output will list clients by distinct entities, non-entity tokens, and total
active clients for each namespace, and the total for the entire cluster. It may
indicate that no data is available for the requested time range, which may be
because the client count reporting is disabled, the time range is too far
in the past, or no data has yet been collected since the feature was enabled.

> Refer to the [Vault Usage Metrics](https://learn.hashicorp.com/tutorials/vault/usage-metrics) tutorial to learn more about usage metrics,
> including required policy and data collection details.

## Examples

Retrieve the client counts for the default reporting period:

```shell-session
$ vault operator usage
Period start: 2019-11-01T00:00:00Z
Period end: 2020-10-31T23:59:59Z

Namespace path   Distinct entities   Non-Entity tokens   Active clients
--------------   -----------------   -----------------   --------------
[root]           1581                332                 1913

Total            1581                332                 1913
```

Retrieve the client counts for a specific month in the past:

```shell-session
$ vault operator usage -start-time=2020-01 -end-time=2020-01
Period start: 2020-01-01T00:00:00Z
Period end: 2020-01-31T23:59:59Z

Namespace path   Distinct entities   Non-Entity tokens   Active clients
--------------   -----------------   -----------------   --------------
[root]           954                 176                 1130

Total            954                 176                 1130
```

## Usage

The following flags are available in addition to the [standard set of
flags](/docs/commands) included on all commands.

### Output Options

- `-format` `(string: "table")` - Print the output in the given format. Valid
  formats are "table", "json", or "yaml". This can also be specified via the
  `VAULT_FORMAT` environment variable.

### Command Options

- `-start-time` `(date)` - Start month of the report to generate. May be given as YYYY-MM-DD, YYYY-MM-DD,
  a full RFC3339 timestamp, or a Unix epoch timestamp. Defaults to the configurable `default_report_months`
  prior to `end-time`.

- `-end-time` `(date: previous month)` - End month of the report to generate. Defaults to the end of the
  previous calendar month.

The output shows the exact time range being reported, which may not match the input parameters if a full
month is not available, or if the available reports are a subset of the months requested.