Get organization-wide usage

GET

/v1/usage

const url = 'https://api.overwatch.weareheavy.dev/v1/usage?period=2026-06';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.overwatch.weareheavy.dev/v1/usage?period=2026-06' \
  --header 'Authorization: Bearer <token>'

The organization’s usage from the billing ledger: a monthly trend plus the per-site breakdown for one period. Deleted sites still appear under their hostname — billing outlives site churn.

Session-only, owner/admin: a site-scoped CMS key has no business reading org-wide aggregates.

Authorizations

BearerAuth

Parameters

Query Parameters

period

string

/^\d{4}-\d{2}$/

Example

2026-06

Billing period as YYYY-MM. Defaults to the latest month with usage.

Responses

200

Monthly trend plus the selected period’s per-site breakdown.

application/json

object

byMonth

required

Array<object>

One month of crawl usage.

object

billing_period

required

UTC billing period, YYYY-MM.

string

runs

required

integer

pages_crawled

required

integer

links_checked

required

integer

period

required

The period bySite describes, or null when there is no usage yet.

string | null

bySite

required

Array<object>

One site’s usage within a billing period.

object

site_id

required

string format: uuid

hostname

required

Denormalized at crawl time, so deleted sites still appear.

string

runs

required

integer

pages_crawled

required

integer

links_checked

required

integer

Example

{
  "byMonth": [
    {
      "billing_period": "2026-06"
    }
  ]
}

401

Missing or invalid credentials.

application/json

object

error

required

A human-readable error message.

string

Example

{
  "error": "invalid api key"
}

403

A dashboard session is required (API-key callers are rejected), or the session’s role does not allow this action.

application/json

object

error

required

A human-readable error message.

string

Example

{
  "error": "a dashboard session is required"
}