# Get per-endpoint bandwidth breakdown

Returns bandwidth usage broken down by endpoint (screenshots, recordings, scrape, scrape_md, fetch, fetch_md, crawl, crawl_links, sitemap, monitors) for a date range. Each row carries raw bytes, the billing multiplier, and billable bytes. Endpoints with zero raw bytes for the range are omitted from `rows`; `totals` is always present. Default range is the last 30 days; max 366 days.

**GET** `/v1/usage/by-endpoint`

## Parameters

- `from` (query, string) — Start date (YYYY-MM-DD). Default 30 days ago.
- `to` (query, string) — End date (YYYY-MM-DD). Default today.
- `api_key` (query, string) — Filter by API key (prefixed ID, e.g. `ak_xxx`). When provided, scopes the breakdown to that key only. The key must belong to the requesting account; cross-account keys return an empty breakdown. When absent, aggregates across all keys.

## Responses

### 200 — Successful response.
- `from`
- `to`
- `rows`
- `rows.endpoint`
- `rows.raw_bytes`
- `rows.multiplier`
- `rows.billable_bytes`
- `totals`
- `totals.raw_bytes`
- `totals.billable_bytes`

### 401 — Unauthorized. The request carried no valid credential, and no work was
performed. The unified `Error` envelope carries one of the codes below
in `error.code`; match on the code, never on the prose.

- `invalid_api_key` — a bearer API key was presented and rejected:
  unknown, revoked, expired or malformed. The bearer-only operations
  (`/v1/webhook-deliveries*` among them) also return it when no
  `Authorization` header is sent. `GET /v1/account` is the exception
  to "malformed": it returns `invalid_api_key` only for a key that
  starts `sk_test_` or `sk_live_` and is unknown, revoked or expired.
- `unauthorized` — the `Authorization` header is absent or malformed on
  an operation that also accepts a dashboard session (the dual-auth and
  billing operations). `GET /v1/account` also returns it, for no
  `Authorization` header and for any bearer value that does not start
  `sk_test_` or `sk_live_` (that value is checked as a dashboard
  session token).

Not retryable as-is: supply a valid API key first.
- `status`
- `error`
- `error.code`
- `error.message`
- `error.http_status`
- `error.failed_at`
- `error.details`