docs(usage): update public API and MCP guides for v2

.github/scripts/check-broken-links.mjs

@@ -0,0 +1,16 @@
+import { getBrokenInternalLinks } from '@mintlify/link-rot';
+import { join } from 'node:path';
+import { getNavigationPages } from './api-navigation.mjs';
+
+const root = process.cwd();
+const generated = new Set(getNavigationPages(root).filter(page => page.operation).map(page => page.slug));
+const broken = (await getBrokenInternalLinks(root)).filter(link => !generated.has(link.toString()));
+
+if (broken.length > 0) {
+  for (const link of broken) {
+    console.error(`${join(link.relativeDir, link.filename)}: ${link.originalPath}`);
+  }
+  process.exitCode = 1;
+} else {
+  console.log(`No broken internal links found; checked ${generated.size} generated API destinations.`);
+}

.github/workflows/static-docs-checks.yml

@@ -2,7 +2,7 @@ name: Static docs checks
 
 # Runs static validations on every PR — works without a Mintlify preview URL,
 # so it fills the gap for PRs (e.g. the auto-update API spec ones) where the
-# preview deployment is skipped or fails. Fails the PR if `mint broken-links`
+# preview deployment is skipped or fails. Fails the PR if `npm run check:links`
 # reports any broken internal links.
 #
 # Required check in the branch ruleset. When no docs files changed the
@@ -108,7 +108,7 @@ jobs:
         run: |
           REPORT=$(mktemp)
           STATUS=0
-          npx mint broken-links > "$REPORT" 2>&1 || STATUS=$?
+          npm run check:links > "$REPORT" 2>&1 || STATUS=$?
           {
             echo "## Broken-links scan"
             echo ""

API-DOCUMENTATION.md

@@ -1,4 +1,4 @@
 # API Reference Documentation Architecture
 
 This document outlines how the API reference section works.
 
@@ -31,40 +31,42 @@
 
 ### `docs.json`
 
 Defines the navigational structure of the docs. The "API" section determines the sidebar navigation structure of the API reference. Each path points to an MDX page in `/api-reference`.
 
 Usage v2 and legacy Status Pages entries instead reference a schema operation, such as `"api-reference/openapi.json GET /v2/usage/summary"`. Mintlify generates these pages directly from the schema in their existing navigation positions.
 
 ### `api-reference/{category}/\*.mdx`
 
 Each page has an `openapi` attribute that points to an endpoint listed in `api-reference/openapi.json`. Mintlify auto-generates the documentation based on this information.
 
 ### `api-reference/openapi.json`
 
 Contains a copy of the OpenAPI spec that all our API reference pages pull from. It's automatically updated every 48 hours by our [Github Actions](https://github.com/checkly/docs/actions/workflows/update-api-spec.yml) workflow.
 
 ### Endpoint status badges and warnings
 
-Usage v2 operations declare the Beta badge in `x-mint.metadata.tag`. Legacy Status Pages operations use the standard `deprecated: true` flag, which Mintlify renders as a deprecation label. Both include a native `<Warning>` component through `x-mint.content`. Set this metadata in the backend routes so API spec refreshes preserve it.
+Usage v2 operations declare the Beta badge in `x-mint.metadata.tag`. Deprecated operations, including Usage v1 and legacy Status Pages, use the standard `deprecated: true` flag. Mintlify renders this flag as a deprecation label. Set lifecycle metadata in the backend routes so API spec refreshes preserve it. Add guidance through `x-mint.content` for a generated page or a `<Warning>` in an authored MDX page. A badge alone does not add warning content.
 
 The operation's `x-mint.href` preserves its existing page URL. `x-mint.metadata` also carries authored titles, descriptions, and the trailing-slash canonical URL. Keep these URL fields when changing an endpoint's lifecycle status.
 
 Do not add an MDX file at a generated page's URL. Mintlify processes existing MDX files after generating endpoints and would overwrite the schema metadata and content. The shared API navigation tooling checks for this conflict and validates generated canonicals. Sitemap generation, legacy redirect checks, and endpoint discovery resolve these entries through `x-mint.href`.
 
+Run `npm run check:links` to validate internal links. This uses Mintlify's link checker and recognizes schema-generated destinations through the shared navigation resolver. The CLI's `mint broken-links` command alone only recognizes files on disk and reports links to generated API pages as missing.
+
 ## Updating `api-reference/openapi.json` via Github Actions
 
 Checkly's public OpenAPI spec can be found here: https://api.checklyhq.com/openapi.json. We have a copy saved to `api-reference/openapi.json` that we update every 48 hours. This copy is formatted to play nicely with how Mintlify renders pages, and all our API reference pages use this file to auto-generate the API reference documentation.
 
 * `.github/workflows/update-api-spec.yml` runs the update script (`update-api-spec.sh`) every 48 hours and commits the changes to `main`. [View all recent runs.](https://github.com/checkly/docs/actions/workflows/update-api-spec.yml)
 
 * The update script (`update-api-spec.sh`) pulls the most recent OpenAPI spec, cleans it up for use with Mintlify, and applies those edits to `api-reference/openapi.json`.
 
 ## Adding new endpoints
 
 Choose how the endpoint page is created:
 
 * For a native schema-driven page, declare its `x-mint.href`, canonical, and any custom metadata or content in the backend route. Add an operation reference to `docs.json`, such as `"api-reference/openapi.json GET /v2/usage/summary"`. Endpoint discovery also uses native navigation for new operations that declare `x-mint.href`.
 * For an authored MDX page, create a file in `api-reference/{category}/\*.mdx` with an `openapi` attribute referencing the endpoint, and add its file path to `docs.json`.
 
 An authored page can define a custom title. For example:
 ```md
@@ -76,12 +78,12 @@
 
 If you need to update your local copy of the OpenAPI spec, run `./update-api-spec.sh`
 
 That's it! Your new endpoint should be showing properly now.
 
 ## Legacy `/reference/*` redirects
 
 The pre-Mintlify API reference lived on ReadMe.io at `developers.checklyhq.com/reference/<slug>`, where `<slug>` was the lowercased OpenAPI `operationId` (e.g. `getv1checks`). To keep those old deep links alive, `docs.json` carries redirects generated from `.github/reference-slug-map.json` — a **frozen** snapshot of the ReadMe-era slug set. Don't regenerate it from a newer spec: endpoints added after the ReadMe era never had `/reference/` URLs.
 
 * One explicit redirect per historical slug maps to its endpoint page, so old bookmarks deep-link correctly.
 * A trailing catch-all `/reference/:slug*` → `/api-reference/overview` backstops slugs whose endpoints were removed after the ReadMe era. Mintlify resolves exact sources before wildcards, so the catch-all never shadows the explicit entries. **If you ever add a real docs page under `/reference/`, this catch-all will intercept it — narrow or remove it first.**
 * `mint broken-links` does **not** validate these destinations (nothing links to `/reference/*` in page content), so `.github/scripts/check-redirect-destinations.mjs` runs in the static-docs-checks workflow on every docs PR. It validates destinations against both authored MDX and schema-generated pages.

ai/mcp-server/tools.mdx

@@ -244,11 +244,13 @@ Draft a major status page incident for the API outage and wait for confirmation
 
 | Tool | Type | Description |
 | --- | --- | --- |
-| `get-usage-terms` | Read | Return the organization usage terms: contract dates, credit budget, per-unit credit rates, pricing rules, and the accounts covered. Call this first to learn the contract window and the account IDs accepted by the other usage tools. |
-| `get-usage-summary` | Read | Return organization usage totals for a date range plus credit projections, including the `CHECK_RUN` and `AI_INVOCATION` meters. |
-| `list-usage-series` | Read | Return organization usage per period, grouped by account and/or check type, as a zero-filled, cursor-paginated series. Supports `day`, `week`, `month`, and `total` intervals. |
+| `get-usage-terms` | Read | List organization usage terms with dates, budgets, pricing rules, and covered accounts. Supports date filters and cursor pagination. Use returned term IDs in summary and series filters or projection requests. |
+| `get-usage-summary` | Read | Return credits, pricing-rule breakdowns, and coverage gaps across usage terms. Optionally request a whole-term forecast with `projection: { usageTermsId, asOf? }`. |
+| `list-usage-series` | Read | Return cursor-paginated v2 usage for `day`, `week`, `month`, or `total` intervals. Optionally group by account, usage term, pricing rule, and check type. Include calculations, physical run counts, or observed monitor days. |
 
-Usage tools report on the whole organization the account belongs to. Use `accountIds` and `checkTypes` to narrow a report. These tools require an organization usage contract and [`usage:read`](/admin/team-management/permissions) account permission, which Owner and Admin have by default.
+Usage tools use the [v2 Usage API](../../api-reference/usage/overview) and report on the whole organization the selected account belongs to. They require the [`usage:read`](../../admin/team-management/permissions) account permission, which Owner and Admin have by default. Use `usageTermsIds`, `accountIds`, and `pricingRuleKeys` arrays to narrow summary or series. V2 has no `checkTypes` filter. Series defaults to ungrouped daily buckets; pass `groupBy` and `include` as arrays.
+
+`get-usage-terms` returns a `data` collection and `nextId`, including future terms when you omit dates. Summary returns `totals.creditsUsed`, `breakdown`, and `coverage`, rather than v1 meters. To include a forecast, supply one term ID in `projection.usageTermsId`. Its optional `asOf` defaults to yesterday UTC. The forecast covers the term's whole account scope and budget, independently of the report filters. The optional `projection` result contains either `data` or `error`, so an unavailable forecast does not discard a successful summary.
 
 Example prompt:
 

api-reference/usage/get-usage-series.mdx

@@ -1,7 +1,11 @@
 ---
 openapi: get /v1/usage/series
-title: 'Get usage series'
-sidebarTitle: 'Get usage series'
+title: 'Get usage series v1'
+sidebarTitle: 'Get usage series v1'
 description: 'Get paginated usage grouped by time, account, or check type.'
 canonical: 'https://www.checklyhq.com/docs/api-reference/usage/get-usage-series/'
 ---
+
+<Warning>
+  This v1 endpoint is deprecated. Use [v2 series](./get-paginated-consumption-across-usage-terms-group-by-account-usage-term-pricing-rule-and-check-type) for reporting across terms and pricing rules.
+</Warning>

api-reference/usage/get-usage-summary.mdx

@@ -1,7 +1,11 @@
 ---
 openapi: get /v1/usage/summary
-title: 'Get usage summary'
-sidebarTitle: 'Get usage summary'
+title: 'Get usage summary v1'
+sidebarTitle: 'Get usage summary v1'
 description: 'Get usage totals and contract projections for a date range.'
 canonical: 'https://www.checklyhq.com/docs/api-reference/usage/get-usage-summary/'
 ---
+
+<Warning>
+  This v1 endpoint is deprecated. Use [v2 summary](./get-consumption-across-usage-terms-with-a-calculation-breakdown-for-each-pricing-rule) for consumption and [term projections](./project-whole-term-credit-consumption-from-completed-utc-days-using-v2-pricing-rules) for forecasts.
+</Warning>

api-reference/usage/get-usage-terms.mdx

@@ -1,7 +1,11 @@
 ---
 openapi: get /v1/usage/terms
-title: 'Get usage terms'
-sidebarTitle: 'Get usage terms'
+title: 'Get usage terms v1'
+sidebarTitle: 'Get usage terms v1'
 description: 'Get usage terms and accounts for an organization.'
 canonical: 'https://www.checklyhq.com/docs/api-reference/usage/get-usage-terms/'
 ---
+
+<Warning>
+  This v1 endpoint is deprecated. Use the [v2 terms collection](./get-usage-terms-and-accounts-for-the-current-organization) or [retrieve one term](./get-a-usage-term-with-its-budget-accounts-and-applied-pricing-rules).
+</Warning>

api-reference/usage/overview.mdx

@@ -1,55 +1,86 @@
 ---
 title: 'Usage API'
 sidebarTitle: 'Overview'
-description: 'Get usage terms, totals, projections, and time-series data for an organization.'
+description: 'Report organization usage across contracts, inspect credit calculations, and forecast each contract budget.'
 canonical: 'https://www.checklyhq.com/docs/api-reference/usage/overview/'
 ---
 
-The Usage API shows how an organization is using its contract. Use it to check contract terms and credits or export data for reporting.
+The Usage API reports your organization's consumption across usage terms, including renewals. Each charge identifies the term and pricing rule used to calculate it. Use v2 for new integrations.
 
 <Accordion title="Before you begin">
-  You need a user or service API key with the **Owner** or **Admin** role for an account in the organization. Send the key in the `Authorization: Bearer <api-key>` header. Send the account ID in the `X-Checkly-Account` header. Legacy account API keys are not supported. See [Using the Checkly API](../overview) for authentication details.
+  You need a user or service API key with the [`usage:read`](../../admin/team-management/permissions#usage) permission for an account in the organization. Owner and Admin have this permission by default. Send the key in the `Authorization: Bearer <api-key>` header and the account ID in the `X-Checkly-Account` header. Legacy account API keys are not supported. See [Using the Checkly API](../overview) for authentication details.
 </Accordion>
 
+<Note>
+  The v2 endpoints are in beta and may change without notice. The v1 usage endpoints are deprecated and remain available for existing integrations.
+</Note>
+
 ## Choose an endpoint
 
 | Endpoint | Use it to |
 | --- | --- |
-| [`GET /v1/usage/terms`](./get-usage-terms) | Get contract dates, credit rates, and organization accounts. |
-| [`GET /v1/usage/summary`](./get-usage-summary) | Get totals and projections for a date range. |
-| [`GET /v1/usage/series`](./get-usage-series) | Get paginated usage grouped over time. |
+| [`GET /v2/usage/terms`](./get-usage-terms-and-accounts-for-the-current-organization) | List usage terms, including contract dates, credit budgets, pricing rules, and covered accounts. |
+| [`GET /v2/usage/terms/{id}`](./get-a-usage-term-with-its-budget-accounts-and-applied-pricing-rules) | Retrieve one term by ID. |
+| [`GET /v2/usage/summary`](./get-consumption-across-usage-terms-with-a-calculation-breakdown-for-each-pricing-rule) | Get total credits and calculations by term and pricing rule. |
+| [`GET /v2/usage/series`](./get-paginated-consumption-across-usage-terms-group-by-account-usage-term-pricing-rule-and-check-type) | Get paginated usage over time, with optional grouping and measurement details. |
+| [`GET /v2/usage/terms/{id}/projections`](./project-whole-term-credit-consumption-from-completed-utc-days-using-v2-pricing-rules) | Forecast consumption against one term's budget. |
+
+## Select terms and dates
+
+Dates use inclusive UTC `YYYY-MM-DD` values.
 
-## Resolve usage terms and dates
+The terms collection lists all terms, including future terms, when you omit dates. Set `from` and `to` to list terms that overlap that range. To find terms active on one date, pass that date as both values. Read terms from `data` and follow `nextId` until it is null.
 
-The API uses `to` to select the contract active on that date. If you omit `to`, it uses today's date.
+Summary and series default `to` to today and `from` to the earliest selected usage start on or before `to`. If no terms exist, `from` defaults to `to`. A report can cover at most 3,661 dates. Reports can span renewals, while each term retains its own prices and budget.
 
-Dates use `YYYY-MM-DD` and include both the start and end date. If you omit `from`, the API uses the contract's `usageStartDate`. The API trims dates that fall outside the contract's usage window. Series responses include a `PARTIAL_WINDOW` warning when this happens.
+`coverage.gaps` lists dates outside the organization's usage terms, including dates before usage starts. A summary or ungrouped series bucket spanning a gap has null credits. When you group by term, covered terms retain their calculated charges and uncovered dates have a separate row. Deliberately filtering out a term does not create a gap.
 
 ## Filter and group usage
 
-Summary and series requests accept `accountIds` and `checkTypes`. Repeat a parameter or separate values with commas. Omit `accountIds` to include every account in the selected contract.
+Summary and series accept `usageTermsIds`, `accountIds`, and `pricingRuleKeys`. Repeat a parameter or separate values with commas. Without an account filter, reports include the selected terms' organization accounts. V2 has no `checkTypes` filter.
+
+Series also accepts:
+
+- `interval`: `day`, `week`, `month`, or `total`. The default is `day`. Weeks start on Monday and months follow the UTC calendar. Boundary buckets are clipped to the report range.
+- `groupBy`: any combination of `account`, `usageTerm`, `pricingRule`, and `checkType`. The default is ungrouped. Repeat the parameter or separate values with commas.
+- `include`: any combination of `calculations`, `runs`, and `monitorDays`. These fields are omitted unless requested.
+- `limit`: from 1 to 500 rows per page. The default is 100.
+- `nextId`: the opaque cursor from the previous page.
+
+For example, request daily usage grouped by account, pricing rule, and check type, with pricing and measurement details:
+
+```http
+GET /v2/usage/series?from=2026-09-01&to=2026-09-30&groupBy=account,pricingRule,checkType&include=calculations,runs,monitorDays
+```
+
+## Interpret credits and measurements
+
+Summary returns `totals.creditsUsed`, `breakdown`, and `coverage`. Each series row returns `periodStart`, `periodEnd`, `dimensions`, `creditsUsed`, and `contributions`. Summary breakdowns include the applied pricing rule and calculations. Add `include=calculations` for those details in series contributions.
+
+Zero credits means calculated zero consumption. Null credits means the API cannot calculate the charge, for example because of uncovered dates or unavailable or incompatible pricing. A rule absent from an otherwise configured term contributes zero credits while retaining measured quantities.
+
+Pricing quantities depend on the rule. API and browser checks use runs, Multistep checks use requests, and Playwright suites use metered 30-second intervals. V2 also prices recorded trace conditions, uptime, AI invocations, status pages, SMS, and phone alerts. Included allowances and conditional rates can change billable quantities and prices.
+
+`include=runs` adds physical check-run counts: `totalRuns`, `finalRuns`, `retryRuns`, `cancelledRuns`, `degradedRuns`, `failedRuns`, `errorRuns`, `abortedRuns`, and `overMaxResponseTimeRuns`. Outcome flags can overlap. These counts are independent of billed quantities.
 
-The series endpoint also supports:
+`include=monitorDays` adds observed uptime monitor resource-days. Repeated runs for the same account, monitor, check type, and UTC date count once. Uptime pricing charges one organization-day when at least one monitor records usage, regardless of monitor count. Grouped measurement rows can therefore have zero credits alongside a shared uptime charge.
 
-- `interval`: `day`, `week`, `month`, or `total`. The default is `day`. Weekly buckets start on Monday. Monthly buckets follow calendar months.
-- `groupBy`: `account`, `checkType`, or `account,checkType`. The default is `account,checkType`.
-- `limit`: From 1 to 500 rows per page. The default is 100.
-- `nextId`: the opaque cursor from the previous response.
+Covered empty rows have zero measurement counts. Counts are null when a bucket includes uncovered dates, unless the row identifies a covered term. Adding measurement details or changing grouping does not change credits.
 
-The API orders rows by period, account ID, and check type. It includes rows with zero usage, so clients do not have to fill gaps before building tables or charts.
+## Project one term's budget
 
-## Interpret metrics and credits
+Projections use the selected term's whole account scope and budget. Summary and series filters do not apply. Request each renewal's projection separately.
 
-Summary totals and series rows include `credits` and a `CHECK_RUN` meter. The meter reports run outcomes, billable units, Multistep requests, and Playwright billable duration in milliseconds.
+The optional `asOf` date defaults to yesterday UTC. Today and future dates are rejected. The response includes credits used, remaining credits, the budgeted daily pace, and four windows: `sinceStart`, `last30Days`, `last7Days`, and `last1Day`. Each window reports its actual observed period, daily average, projected contract-end consumption, projected remaining credits, budget percentages, and estimated time until credits run out.
 
-The API calculates `credits.used` from standard and premium billable units using the contract's rates.
+The forecast extrapolates observed credit consumption. It does not predict resource changes or future allowance exhaustion. Unknown prices or budgets can make derived fields null. V2 summary does not embed projections.
 
-Summary projections cover usage since `usageStartDate`, the last 30 days, the last 7 days, and the last day. They show annualized budget use, projected usage at the end of the contract, and the estimated time until credits run out.
+## Paginate live results
 
-## Paginate a series
+Terms and series return an opaque `nextId`. Send it unchanged with the same resolved dates, filters, and series options to retrieve the next page. A null cursor marks the last page. You can change the page size or reorder equivalent filters. Other query changes require starting pagination again.
 
-Send a non-null `nextId` unchanged with the same query parameters to retrieve the next page. Changing a parameter invalidates the cursor.
+Each page reads current measurements and prices. Late usage or pricing corrections can change values between pages; cursors do not freeze a snapshot.
 
 ## Handle errors
 
-The API returns `400` for invalid requests, `401` or `403` for authentication and permission errors, and `404` when no matching usage terms are found.
+Invalid dates, ranges, filters, or cursors return `400`. Authentication and permission errors return `401` or `403`. An unknown or inaccessible term returns `404`; an empty terms collection returns `200` with `data: []`. Overlapping selected terms return `409`, rate limits return `429`, and unavailable usage storage returns `502`.

docs.json

@@ -954,14 +954,14 @@
                 "group": "Usage",
                 "pages": [
                   "api-reference/usage/overview",
-                  "api-reference/usage/get-usage-terms",
-                  "api-reference/usage/get-usage-summary",
-                  "api-reference/usage/get-usage-series",
                   "api-reference/openapi.json GET /v2/usage/terms",
                   "api-reference/openapi.json GET /v2/usage/series",
                   "api-reference/openapi.json GET /v2/usage/summary",
                   "api-reference/openapi.json GET /v2/usage/terms/{id}",
-                  "api-reference/openapi.json GET /v2/usage/terms/{id}/projections"
+                  "api-reference/openapi.json GET /v2/usage/terms/{id}/projections",
+                  "api-reference/usage/get-usage-terms",
+                  "api-reference/usage/get-usage-summary",
+                  "api-reference/usage/get-usage-series"
                 ]
               },
               {