--- title: "Get usage series" method: GET path: "/v2/usage/series" tags: ["Usage"] --- # Get usage series `GET /v2/usage/series` ## Request - Base URL: `https://api.checklyhq.com` - URL: `https://api.checklyhq.com/v2/usage/series` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Get paginated consumption across usage terms. Group by account, usage term, pricing rule and check type. ## Query parameters - `from` string, date: Inclusive UTC date. Defaults to the earliest selected usage start, or to. - `to` string, date: Inclusive UTC date. Defaults to today. - `usageTermsIds` string[] - `accountIds` string[] - `pricingRuleKeys` string[] - `limit` integer - `nextId` string: Query-bound cursor. Live reads do not freeze measurements or prices. - `interval` 'total' | 'day' | 'week' | 'month': Monday weeks and calendar months; boundary buckets are clipped. - `groupBy` string[] - `include` string[] ## Headers - `x-checkly-account` string, uuid: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general ## Response `200` Successful - UsageV2SeriesResponse - `period` object, required - `from` string, date, required - `to` string, date, required - `usageTermsIds` string[], required - `interval` 'total' | 'day' | 'week' | 'month', required - `groupBy` string[], required - `data` UsageV2SeriesRow[], required - `periodStart` string, date, required - `periodEnd` string, date, required - `dimensions` object, required - `accountId` string - `usageTermsId` string, uuid - `pricingRuleKey` 'apiChecks' | 'multistepChecks' | 'browserChecks' | 'playwrightCheckSuites' | 'uptimeMonitors' | 'aiInvocations' | 'statusPages' | 'statusPageAdditionalServices' | 'statusPageAdditionalSubscribers' | 'additionalSms' | 'additionalPhoneAlerts' - `checkType` 'AGENTIC' | 'API' | 'BROWSER' | 'HEARTBEAT' | 'ICMP' | 'MULTI_STEP' | 'TCP' | 'PLAYWRIGHT' | 'URL' | 'DNS' | 'SSL' | 'GRPC' | 'TRACEROUTE' | 'null', nullable: Present when grouping by checkType. Null means usage has no attributable check type. - `creditsUsed` number, nullable, required: Credits rounded to four decimals before aggregation: once per organization-day for uptime monitors, and per resource-day and applied rate for other usage. Rules absent from configured pricing contribute zero. Null means unavailable or incompatible pricing, or uncovered dates. - `contributions` UsageV2Contribution[], required - `usageTermsId` string, uuid, required - `pricingRuleKey` 'apiChecks' | 'multistepChecks' | 'browserChecks' | 'playwrightCheckSuites' | 'uptimeMonitors' | 'aiInvocations' | 'statusPages' | 'statusPageAdditionalServices' | 'statusPageAdditionalSubscribers' | 'additionalSms' | 'additionalPhoneAlerts', required - `creditsUsed` number, nullable, required: Credits rounded to four decimals before aggregation: once per organization-day for uptime monitors, and per resource-day and applied rate for other usage. Rules absent from configured pricing contribute zero. Null means unavailable or incompatible pricing, or uncovered dates. - `period` object - `from` string, date, required - `to` string, date, required - `pricingRule` union - object - `method` 'per_unit', required - `quantity` number, required - `unit` string, required - `credits` number, required - `rates` object[] - `when` string, required - `credits` number, required - `included` object - `quantity` number, required - `period` string - object - `method` 'per_period', required - `period` 'day', required - `price` object, required - `annualCredits` number, required - object - `method` 'capacity_blocks_per_period', required - `period` 'day', required - `unit` string, required - `included` object, required - `quantity` number, required - `block` object, required - `quantity` number, required - `annualCredits` number, required - `calculations` UsageV2Calculation[] - union - object - `rateCondition` string, nullable, required - `measuredQuantity` number, required - `includedQuantity` number, nullable, required - `billableQuantity` number, nullable, required - `creditsUsed` number, nullable, required: Credits rounded to four decimals before aggregation: once per organization-day for uptime monitors, and per resource-day and applied rate for other usage. Rules absent from configured pricing contribute zero. Null means unavailable or incompatible pricing, or uncovered dates. - object - `billableResourceDays` number, required - `appliedDailyCredits` number, required - `proration` object, required - … - `creditsUsed` number, nullable, required: Credits rounded to four decimals before aggregation: once per organization-day for uptime monitors, and per resource-day and applied rate for other usage. Rules absent from configured pricing contribute zero. Null means unavailable or incompatible pricing, or uncovered dates. - object - `scope` 'statusPage', required - `measuredQuantity` number, required - `includedQuantity` number, required - `billableBlockDays` number, required - `appliedDailyCreditsPerBlock` number, required - `proration` object, required - … - `creditsUsed` number, nullable, required: Credits rounded to four decimals before aggregation: once per organization-day for uptime monitors, and per resource-day and applied rate for other usage. Rules absent from configured pricing contribute zero. Null means unavailable or incompatible pricing, or uncovered dates. - `monitorDays` integer, nullable: Present with include=monitorDays. Observed uptime monitor resource-days, independent of the shared organization-day charge. Repeated runs of a monitor on the same UTC day count once per check type. Zero for covered empty usage; null for uncovered dates. - `runs` object, nullable: Present with include=runs. Zero for covered empty usage; null when the bucket includes uncovered dates. - `totalRuns` integer, required - `finalRuns` integer, required - `retryRuns` integer, required - `cancelledRuns` integer, required - `degradedRuns` integer, required - `failedRuns` integer, required - `errorRuns` integer, required - `abortedRuns` integer, required - `overMaxResponseTimeRuns` integer, required - `coverage` object, required: Dates outside organization usage terms. Credits for gaps are unknown; deliberately filtered terms are excluded. - `gaps` object[], required - `from` string, date, required - `to` string, date, required - `nextId` string, nullable, required ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests - `502`: Response ## Changes - **2026-10-31** `bc90d1bfa738`: 7 info - added the optional property `errorCode` to the response with the `400` status - added the optional property `errorCode` to the response with the `401` status - added the optional property `errorCode` to the response with the `403` status - added the optional property `errorCode` to the response with the `404` status - …3 more - **2026-10-17** `4698655f7ecd`: 2 breaking, 5 info - removed the enum value `calculations` from the `query` request parameter `include` - for the `query` request parameter `include`, the minItems was increased from `0` to `1` - for the `query` request parameter `include`, the type was generalized from `string` to `array` - added the optional property `data/items/monitorDays` to the response with the `200` status - …3 more - **2026-10-07** `aba5d34c749b`: 1 info - endpoint added [Operation history](https://skmtc.dev/checklyhq/apis/checkly-public-api/changes/v2/usage/series/get.md) --- [API](https://skmtc.dev/checklyhq/apis/checkly-public-api.md) - [All operations](https://skmtc.dev/checklyhq/apis/checkly-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/checklyhq/apis/checkly-public-api/revisions/bc90d1bfa738?raw)