# Aggregated API usage for the authenticated user.

`GET /usage`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-usage · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetUsage` · Tag: Usage

Returns request volumes, error rates and response times over a recent window, broken down by day, by endpoint and by API key. It answers the questions the audit log in the Wheelhouse app answers, without having to read it request by request: which endpoint dominates your traffic, whether a key is being throttled, when errors started.

Covers every RM API key on the account, not just the one making the request. Pass `token_id` to narrow it to a single key.

**The window is limited to 7 days.** Pass `days_back` for a rolling window ending now, or `start_time` and `end_time` for an explicit one — a window longer than 7 days returns **400**. A window with more requests than can be read in one call sets `window.truncated` to `true` and reports the shorter window actually measured, with the most recent requests always covered.

**Results are cached for a few minutes.** `generated_at` reports when the figures were computed, which is not the same as when they were served: repeat calls inside the cache window return the same numbers. Polling faster than that gains nothing. If what you want is your live rate limit headroom, read the `X-RateLimit-*` headers on any response instead — they are current as of that request and cost nothing extra.

Requests are grouped by the endpoint that served them rather than by the exact path called, so every `GET /listings/{listing_id}/notes` counts towards one entry no matter which listing it named.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/usage`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `days_back` | integer | no | Size in days of a rolling window ending now. Ignored when `start_time` is given. (default: `7`, min: 1, max: 7) |
| `start_time` | string (date-time) | no | Start of an explicit window (ISO-8601). Overrides `days_back`. |
| `end_time` | string (date-time) | no | End of an explicit window (ISO-8601). Defaults to now. |
| `token_id` | integer | no | Restrict the figures to a single RM API key. Must be a key belonging to the authenticated user; the `id` values returned in `by_token` are valid here. |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/usage' \
  -H 'X-Integration-Api-Key: <your RM API key>'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 200

Usage figures for the window.

Body (`application/json`): object `usage_response`

- `generated_at` (string (date-time)): When these figures were computed (ISO-8601). Repeat calls within the cache window return the same value.
- `window` (object)
  - `start` (string (date-time)): Start of the window the figures cover (ISO-8601).
  - `end` (string (date-time)): End of the window the figures cover (ISO-8601).
  - `truncated` (boolean): Whether the window was too busy to measure in full. When `true`, `start` has been moved forward to the oldest request actually counted, and every figure below covers that shorter window.
- `totals` (object)
  - `requests` (integer): Requests made in the window.
  - `by_status_class` (map of string to integer): Requests by response status class. `2xx`, `3xx`, `4xx` and `5xx` are always present; other classes appear only if observed.
  - `rate_limited` (integer): Requests rejected with 429 Too Many Requests. Also counted under `4xx`.
  - `avg_response_ms` (number, nullable): Mean server-side response time in milliseconds. `null` if no requests were made.
  - `p95_response_ms` (number, nullable): 95th-percentile server-side response time in milliseconds. `null` if no requests were made.
- `by_day` (array of object): One entry per UTC day on which requests were made, oldest first. Days with no traffic are omitted.
  - `date` (string (date)): The UTC day (YYYY-MM-DD).
  - `requests` (integer)
  - `errors` (integer): Requests that returned 4xx or 5xx.
- `by_endpoint` (array of object): One entry per endpoint, busiest first. Paths are reported as route patterns, so all requests to the same endpoint are grouped regardless of which listing or resource they named.
  - `method` (string, example: `GET`)
  - `path` (string, example: `/listings/{listing_id}/notes`): The route pattern, relative to the API base path. `other` covers requests that matched no endpoint.
  - `requests` (integer)
  - `errors` (integer): Requests that returned 4xx or 5xx.
  - `avg_response_ms` (number, nullable): Mean server-side response time in milliseconds for this endpoint.
- `by_token` (array of object): One entry per RM API key that made requests in the window, busiest first.
  - `id` (integer)
  - `name` (string, nullable): The name given to the key, or `null` if it has been revoked or was never named.
  - `last_chars` (string, nullable): The last four characters of the key, as shown in the Wheelhouse app.
  - `requests` (integer)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "generated_at": "2026-01-01T00:00:00Z",
  "window": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-01T00:00:00Z",
    "truncated": true
  },
  "totals": {
    "requests": 0,
    "by_status_class": {
      "key": 0
    },
    "rate_limited": 0,
    "avg_response_ms": 0,
    "p95_response_ms": 0
  },
  "by_day": [
    {
      "date": "2026-01-01",
      "requests": 0,
      "errors": 0
    }
  ],
  "by_endpoint": [
    {
      "method": "GET",
      "path": "/listings/{listing_id}/notes",
      "requests": 0,
      "errors": 0,
      "avg_response_ms": 0
    }
  ],
  "by_token": [
    {
      "id": 0,
      "name": "string",
      "last_chars": "string",
      "requests": 0
    }
  ]
}
```

### 400

The requested window is longer than 7 days, `start_time` is after `end_time`, or `days_back` is out of range.

### 401

API key authorization failed.

### 404

No such API key belongs to the authenticated user.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
