> ## Documentation Index
> Fetch the complete documentation index at: https://www.unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# unkey logs api-requests metrics

> Count API requests per time bucket, grouped by HTTP status class.

> [!NOTE]
>
> Create a root key with the permissions listed on this page under **Root Keys** in the dashboard sidebar. CLI commands can instead use a session from [unkey login](https://www.unkey.com/docs/platform/cli/login.md) with the required permissions. See [Permission reference](https://www.unkey.com/docs/platform/root-keys/permissions-legacy.md) for every permission.

Count the requests that the Unkey API served for your workspace per time bucket, split by status class.

The filters have the same shape as in `logs.listApiRequests`, without `requestId`. In one field, values under `is`, `contains`, `startsWith`, and `endsWith` are combined with OR. Values under `isNot` and `notContains`, and the range operators `gt`, `gte`, `lt`, and `lte`, are combined with AND. Different fields are combined with AND. Every text match is exact and case-sensitive.

`filters.time` sets the window. A missing lower bound is the start of your log retention, and a missing upper bound is now. Unkey picks the bucket width from the window. It is the distance between the `time` of two points. The first bucket starts at or before the window start and counts its whole width. Windows reach back at most 100 days, and requests outside the log retention of your workspace are not counted.

## Usage

```bash theme={"system"}
unkey logs api-requests metrics [flags]
```

## Flags

**--filters** `string`

A JSON object. Filters for the metrics. They have the same shape as the filters of `logs.listApiRequests`, without `requestId`. A missing field does not filter. Different fields are combined with AND.

**Properties**

**time** `object`

Filters by the time of the event, in Unix milliseconds. Every bound is combined with AND. Rows older than the workspace's retention are never returned or counted, whatever the bounds.

**Operators**

**gt** `integer`

Keep events after this time.

**gte** `integer`

Keep events at or after this time.

**lt** `integer`

Keep events before this time.

**lte** `integer`

Keep events at or before this time.

**path** `object`

Filters a text field. Every operator is exact and case-sensitive. `%` and `_` match only themselves. The positive operators (`is`, `contains`, `startsWith`, `endsWith`) are combined with OR. The negated operators (`isNot`, `notContains`) are combined with AND.

**Operators**

**is** `string[]`

Keep rows where the field equals one of the values. At most 10 values.

**isNot** `string[]`

Remove rows where the field equals one of the values. At most 10 values.

**contains** `string[]`

Keep rows where the field contains one of the values. At most 10 values.

**notContains** `string[]`

Remove rows where the field contains one of the values. At most 10 values.

**startsWith** `string[]`

Keep rows where the field starts with one of the values. At most 10 values.

**endsWith** `string[]`

Keep rows where the field ends with one of the values. At most 10 values.

**method** `object`

Filters by HTTP method.

**Operators**

**is** `string[]`

Keep rows with one of these methods. Values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.

**isNot** `string[]`

Remove rows with one of these methods. Values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.

**status** `object`

Filters an integer field. `is` keeps rows that equal one of its values. `isNot` and every bound (`gt`, `gte`, `lt`, `lte`) are combined with AND, so `{ "is": [200], "gte": 400 }` matches no rows.

**Operators**

**is** `integer[]`

Keep rows where the field equals one of the values. At most 10 values.

**isNot** `integer[]`

Remove rows where the field equals one of the values. At most 10 values.

**gt** `integer`

Keep rows where the field is greater than this value.

**gte** `integer`

Keep rows where the field is greater than or equal to this value.

**lt** `integer`

Keep rows where the field is less than this value.

**lte** `integer`

Keep rows where the field is less than or equal to this value.

### Shared flags

These flags control authentication, requests, and output. [CLI output and shared flags](https://www.unkey.com/docs/platform/cli/output-and-flags.md) describes them in full.

**--body** `string`

A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See [Send a raw body](https://www.unkey.com/docs/platform/cli/output-and-flags.md#send-a-raw-body).

**--root-key** `string`

Root key used for the request. Falls back to `UNKEY_ROOT_KEY`, then stored credentials, including a CLI session. See [CLI authentication](https://www.unkey.com/docs/platform/cli/authentication.md) for the full precedence order.

**--api-url** `string` (default: [https://api.unkey.com](https://api.unkey.com))

Base URL of the API. Falls back to `UNKEY_API_BASE_URL`. You don't normally need to set it.

**--config** `string` (default: \~/.unkey/config.toml)

Path of the TOML config file. Falls back to `UNKEY_CONFIG`. An explicit `--config` takes precedence over a stored CLI session. Browser login stores a session, not a root key in this file. See [CLI authentication](https://www.unkey.com/docs/platform/cli/authentication.md).

**--output** `enum` (default: human)

Use `human` (default) for name-first summary tables and labeled details, or `json` for the unchanged full response envelope, including all fields and pagination. Terminal tables use relative timestamps and may shorten display names and descriptions, but never identifiers, slugs, or credentials. Redirected human output keeps complete values and uses RFC3339 UTC timestamps. Falls back to `UNKEY_OUTPUT`; other values are rejected. `--json` also selects JSON output. Add `--debug` to print the request ID to stderr. See [Output formats](https://www.unkey.com/docs/platform/cli/output-and-flags.md#output-formats).

**--debug** `boolean`

Print the successful response's request ID to stderr, separate from stdout.

**--json** `boolean`

Print the full response as JSON. Takes precedence over a valid `--output` or `UNKEY_OUTPUT` value.

## Required permissions

Your root key must have the following permission:

* `unkey:v1:<workspace_id>:logs/apiRequests#read`

See [Root key permissions](https://www.unkey.com/docs/platform/root-keys/permissions.md).

## Examples

```bash theme={"system"}
unkey logs api-requests metrics --filters='{"status":{"gte":400,"lt":600}}'
```

Send the request body as JSON:

```bash theme={"system"}
unkey logs api-requests metrics --body='{"filters":{"status":{"gte":400,"lt":600}}}'
```

## API endpoint

The command calls `POST /v2/logs.getApiRequestMetrics` and prints its response. See the [endpoint definition](https://github.com/unkeyed/unkey/blob/main/svc/api/openapi/spec/paths/v2/logs/getApiRequestMetrics/index.yaml) for the HTTP contract. Request fields use camelCase in `--body`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.