# GET /v1/usage/by-key

> GetByKey

- `operationId`: `V1UsageByKeyGetByKey`
- Group: [Usage](https://sference.com/docs/api-reference/usage.md)
- API spec (machine-readable): https://sference.com/openapi.json
- HTML version: https://sference.com/docs/api-reference/usage/V1UsageByKeyGetByKey

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | Rolling window |
| `month` | query | string \| null | no | Calendar month YYYY-MM; overrides `days` |
| `tag` | query | string \| null | no | Filter to one key tag |

## Responses

### `200` — Request fulfilled, document follows

Schema: `UsageByKeyResponse`

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| `period_start` | string | yes | date-time | — |
| `period_end` | string | yes | date-time | — |
| `items` | array<UsageByKeyItem> | yes | — | — |
| `by_tag` | array<UsageByTagItem> | no | — | — |

### `400` — Bad request

Schema: `ApiErrorResponse`

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| `detail` | ApiError | yes | — | — |

Source: https://sference.com/docs/api-reference/usage/V1UsageByKeyGetByKey
