Skip to content
Overwatch API

Quotas & usage

Overwatch meters every app into a usage ledger and enforces per-site allowances with a pause-by-default overage model. This guide covers what the allowances are, what happens when one runs out, and how to read usage.

Allowances

Section titled “Allowances”

The subscription includes a number of sites (returned as quota.included on GET /v1/sites), and each site carries monthly per-app allowances:

  • Pages crawled — 5,000 per site per billing period (the Broken Links crawl).
  • Pages rendered — 1,000 per site per period (the Accessibility scan’s headless rendering).
  • Uptime monitors — 2 per site, pooled across the organization.

The current numbers are always available from the API: GET /v1/sites/{id}/usage returns each site’s meters and allowances, and GET /v1/billing (session-only, owner/admin) returns the full picture.

Pause by default, overage by opt-in

Section titled “Pause by default, overage by opt-in”

What happens at an allowance boundary depends on the account’s overage opt-in (overageEnabled, flipped via PATCH /v1/billing, session-only):

  • Overage off (default): the app pauses for the rest of the period — the scheduler skips crawls or scans for that site (visible as crawlPaused/a11yPaused on GET /v1/billing), registering a site past the included count is refused with 403, and so is creating a monitor past the allowance. A notification goes out when an allowance is reached. Nothing is ever billed beyond the subscription.
  • Overage on: the apps keep running past their allowances, extra sites and monitors can be created freely, and the excess is metered and billed. The projected bill is itemized on GET /v1/billing.

Flipping overage on un-pauses every paused app from the next scheduler tick; flipping it off re-arms pause-and-notify.

Deleting a site frees its slot immediately.

Organizations per user

Section titled “Organizations per user”

One account may create a limited number of organizations (default 2) — an anti-abuse cap, not a billing dimension. Check yours with GET /v1/me/org-quota (session-only); its canCreate says whether another create would succeed. Raising it goes through a limit-increase request (POST /v1/me/limit-requests, kind user_orgs) that an operator reviews — decisions arrive by email, and the latest request’s status is surfaced on GET /v1/me/org-quota.

The old org_sites request kind is retired: extra sites are self-serve via overage billing.

Usage

Section titled “Usage”

Every finished run appends immutable rows to a usage ledger: which site, how many pages crawled and rendered, how many links checked, and the UTC billing period (YYYY-MM) it falls in. Two read endpoints roll it up:

  • GET /v1/sites/{id}/usage — one site’s monthly totals (oldest → newest) plus the current period’s meters against the allowances. Available to any caller with access to the site, so a CMS integration can show its own consumption.
  • GET /v1/usage — the organization’s monthly trend plus a per-site breakdown for one period (?period=YYYY-MM, default = latest). Session-only, owner/admin — it’s a billing overview.

Two properties worth knowing:

  • The ledger outlives sites. Usage rows carry a denormalized hostname and have no foreign key to the site, so a site deleted mid-month still appears in that month’s breakdown. Deleting a site never erases what it consumed.
  • Runs can’t double-bill. Ledger writes are keyed on the run id, so a retried finalization records usage once.