GET Read account-wide usage and limits
/api/v1/usage
With table=1, returns the complete authorized monitor contributor collection as filtered cursor pages. Sort also accepts items, bytes and planned for descending numeric contributions. The unpaged response remains the account usage summary.
On this page
Access and permissions
With table=1, returns the complete authorized monitor contributor collection as filtered cursor pages. Sort also accepts items, bytes and planned for descending numeric contributions. The unpaged response remains the account usage summary.
Browser session: __Host-mb_session cookie.
Machine management credentials in Authorization: Bearer. Check the permissions (scopes) required by the operation.
Parameters and headers
| Field | Location | Type and limits | Required | Meaning |
|---|---|---|---|---|
| workspace_id | URL query | string; {"format":"uuid"} | No | Select an accessible workspace and its owner account budget. Members see only this workspace’s monitor details. |
| device_id | URL query | string; {"format":"uuid"} | No | Keep this accessible monitor in the bounded breakdown, for editing previews. Foreign or inaccessible monitors return 404. |
| forecast_sort | URL query | string; {"enum":["items","events","bytes","event_bytes","planned","planned_items","planned_events","planned_bytes","planned_event_bytes"],"default":"items"} | No | Select the top 100 monitors by booked objects, booked bytes or planned daily objects before limiting the result. The requested device stays included. |
| table | URL query | string; {"enum":["1"]} | No | Set to 1 for a filtered cursor page; omitting table parameters preserves the original response. |
| q | URL query | string; {"maxLength":128} | No | Case-insensitive literal search in the documented text fields, applied before the page limit. |
| limit | URL query | integer; {"default":50,"maximum":100,"minimum":1} | No | Page size, 1–100; default 50. A following page exists only when another matching row is available. |
| cursor | URL query | string; {"maxLength":4096} | No | Opaque next_cursor from the preceding page. Keep resource, account, filters, sort and limit unchanged; collection cursors expire after 15 minutes. |
| sort | URL query | string; {"enum":["items","bytes","planned","newest","oldest","name_asc","name_desc","events","event_bytes","planned_items","planned_events","planned_bytes","planned_event_bytes","projected_items","projected_events","projected_bytes","projected_event_bytes"]} | No | Stable order with the record ID as a tie breaker: newest, oldest, name_asc or name_desc. |
| type | URL query | string | No | Exact field filter; omit the parameter to include all values. |
| status | URL query | string | No | Exact field filter; omit the parameter to include all values. |
| copy_source | URL query | string; {"enum":["device","workspace"]} | No | Optional metadata-only copy estimate for the selected monitor or workspace. No capacity is reserved. |
| counts_only | URL query | string; {"enum":["1"]} | No | Return counts for the requested filter instead of table rows. Counts include search and other filters, excluding this filter selection, sorting and pagination. |
| count_filter | URL query | string; {"enum":["type","status"]} | No | Declared table filter to count. Requires counts_only=1. |
| snapshot | URL query | string; {"format":"date-time"} | No | Optional snapshot from the corresponding table page. |
Request body
No request body.
Responses
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | JSON | JSON | object | Yes | — |
| $ (anyOf 1) | JSON | JSON | No | — |
| $ (anyOf 1).active_archive_queries_limit | integer; {"minimum":1} | No | Maximum number of concurrent archive queries, including exports. |
| $ (anyOf 1).active_exports_limit | integer; {"minimum":1} | No | Maximum number of concurrent exports. |
| $ (anyOf 1).alarms_limit | integer | No | — |
| $ (anyOf 1).batch_bytes_limit | integer | No | — |
| $ (anyOf 1).batch_items_limit | integer | No | — |
| $ (anyOf 1).bytes_per_minute_limit | integer | No | — |
| $ (anyOf 1).day_bytes | integer | No | — |
| $ (anyOf 1).day_bytes_limit | integer | No | — |
| $ (anyOf 1).day_event_bytes | integer | No | — |
| $ (anyOf 1).day_event_bytes_limit | integer | No | — |
| $ (anyOf 1).day_events | integer | No | — |
| $ (anyOf 1).day_events_limit | integer | No | — |
| $ (anyOf 1).day_items | integer | No | — |
| $ (anyOf 1).day_items_limit | integer | No | — |
| $ (anyOf 1).day_notifications | integer | No | — |
| $ (anyOf 1).day_points | integer | No | — |
| $ (anyOf 1).day_points_limit | integer | No | — |
| $ (anyOf 1).devices | integer | No | — |
| $ (anyOf 1).devices_limit | integer | No | — |
| $ (anyOf 1).events_per_minute_limit | integer | No | — |
| $ (anyOf 1).groups | integer; {"minimum":0} | No | Active groups across all workspaces owned by this account. |
| $ (anyOf 1).groups_limit | integer; {"minimum":1} | No | Effective account limit for active groups. |
| $ (anyOf 1).items_per_minute_limit | integer | No | — |
| $ (anyOf 1).keys | integer | No | — |
| $ (anyOf 1).keys_limit | integer | No | — |
| $ (anyOf 1).limits | object | No | Account limit field: limits. |
| $ (anyOf 1).limits.active_alarms | integer; {"maximum":1099511627776,"minimum":1} | No | Active alert rules. |
| $ (anyOf 1).limits.active_archive_queries | integer; {"maximum":1099511627776,"minimum":1} | No | Queued or running archive queries, including exports. |
| $ (anyOf 1).limits.active_devices | integer; {"maximum":1099511627776,"minimum":1} | No | Active monitors in the account. |
| $ (anyOf 1).limits.active_exports | integer; {"maximum":1099511627776,"minimum":1} | No | Queued or running exports. These also count toward archive query capacity. |
| $ (anyOf 1).limits.active_groups | integer; {"maximum":1099511627776,"minimum":1} | No | Active groups across the account’s workspaces. |
| $ (anyOf 1).limits.active_keys | integer; {"maximum":1099511627776,"minimum":1} | No | Active API keys that have not been revoked. |
| $ (anyOf 1).limits.active_series | integer; {"maximum":1099511627776,"minimum":1} | No | Active measurement series, including reserved series slots. |
| $ (anyOf 1).limits.active_workspaces | integer; {"maximum":1099511627776,"minimum":1} | No | Active workspaces in the account. |
| $ (anyOf 1).limits.alarm_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New alert rules per minute. |
| $ (anyOf 1).limits.batch_bytes | integer; {"maximum":1099511627776,"minimum":1} | No | Bytes per data request. Size limits apply before and after decompression. |
| $ (anyOf 1).limits.batch_items | integer; {"maximum":1099511627776,"minimum":1} | No | Items per data request. |
| $ (anyOf 1).limits.bytes_per_day | integer; {"maximum":1099511627776,"minimum":1} | No | Transferred bytes per UTC day, counted after decompression. |
| $ (anyOf 1).limits.bytes_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | Transferred bytes per minute, counted after decompression. |
| $ (anyOf 1).limits.device_per_day | integer; {"maximum":1099511627776,"minimum":1} | No | New monitors per UTC day. |
| $ (anyOf 1).limits.device_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New monitors per minute. |
| $ (anyOf 1).limits.event_bytes_per_day | integer; {"maximum":1099511627776,"minimum":1} | No | Event data in bytes per UTC day. |
| $ (anyOf 1).limits.event_per_day | integer; {"maximum":1099511627776,"minimum":1} | No | Events per UTC day, in addition to the shared data limit. |
| $ (anyOf 1).limits.event_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | Events per minute, in addition to the shared data limit. |
| $ (anyOf 1).limits.group_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New groups per minute. |
| $ (anyOf 1).limits.key_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New API keys per minute. |
| $ (anyOf 1).limits.live_series_per_connection | integer; {"maximum":1099511627776,"minimum":1} | No | Measurement series per live connection. |
| $ (anyOf 1).limits.notifications_per_day | integer; {"maximum":1099511627776,"minimum":1} | No | Notifications across all channels per UTC day. |
| $ (anyOf 1).limits.notifications_per_hour | integer; {"maximum":1099511627776,"minimum":1} | No | Notifications across all channels per hour. |
| $ (anyOf 1).limits.point_per_day | integer; {"maximum":1099511627776,"minimum":1} | No | New readings and events together per UTC day. |
| $ (anyOf 1).limits.point_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New readings and events together per minute. |
| $ (anyOf 1).limits.request_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | Data submission requests per minute. |
| $ (anyOf 1).limits.series_per_30_days | integer; {"maximum":1099511627776,"minimum":1} | No | New measurement series over the last 30 days. |
| $ (anyOf 1).limits.series_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New measurement series per minute. |
| $ (anyOf 1).limits.workspace_per_minute | integer; {"maximum":1099511627776,"minimum":1} | No | New workspaces per minute. |
| $ (anyOf 1).limits.active_browser_monitors | integer; {"maximum":1000,"minimum":1} | No | — |
| $ (anyOf 1).limits.browser_seconds_per_day | integer; {"maximum":86400,"minimum":1} | No | — |
| $ (anyOf 1).limits.check_artifact_bytes | integer; {"maximum":5368709120,"minimum":1} | No | — |
| $ (anyOf 1).limits.network_checks_per_minute | integer; {"maximum":100000,"minimum":1} | No | — |
| $ (anyOf 1).limits.log_bytes_per_day | integer; {"minimum":1,"maximum":1099511627776} | No | The normal log quota is 1 GiB of normalized, uncompressed accepted entries per UTC day, shared by all workspaces you own. Unverified machine accounts start with 100 MiB. Masking does not reduce billed bytes; filtering does. Logs have a separate budget from measurements and events. Individual increases appear in your account. |
| $ (anyOf 1).limits_version | string; {"pattern":"^[0-9a-f]{64}$"} | No | Version of account type, defaults and individual values. Required when checking or saving changes. |
| $ (anyOf 1).live_series_per_connection_limit | integer; {"minimum":1} | No | Effective limit for measurement series per live connection. |
| $ (anyOf 1).monitors | integer; {"minimum":0} | array<object> | No | — |
| $ (anyOf 1).monitors (oneOf 1) | integer; {"minimum":0} | No | — |
| $ (anyOf 1).monitors (oneOf 2) | array<object> | No | — |
| $ (anyOf 1).monitors (oneOf 2)[] | object | Yes | — |
| $ (anyOf 1).monitors_limit | integer | No | — |
| $ (anyOf 1).new_devices_per_minute_limit | integer | No | — |
| $ (anyOf 1).new_devices_today | integer | No | — |
| $ (anyOf 1).new_devices_today_limit | integer | No | — |
| $ (anyOf 1).new_keys_per_minute_limit | integer | No | — |
| $ (anyOf 1).new_series_30d | integer | No | — |
| $ (anyOf 1).new_series_30d_limit | integer | No | — |
| $ (anyOf 1).new_series_per_minute_limit | integer | No | — |
| $ (anyOf 1).new_workspaces_per_minute_limit | integer | No | — |
| $ (anyOf 1).notifications_per_day_limit | integer | No | — |
| $ (anyOf 1).notifications_per_hour_limit | integer | No | — |
| $ (anyOf 1).points_per_minute_limit | integer | No | — |
| $ (anyOf 1).registration_origin | string | No | Original account registration path. Verification does not change this origin. |
| $ (anyOf 1).requests_per_minute_limit | integer | No | — |
| $ (anyOf 1).series | integer | No | — |
| $ (anyOf 1).series_limit | integer | No | — |
| $ (anyOf 1).tier | string | No | — |
| $ (anyOf 1).workspaces | integer | No | — |
| $ (anyOf 1).workspaces_limit | integer | No | — |
| $ (anyOf 1).forecast | UsageForecast | No | Consistent read-only snapshot of effective quotas, daily booked consumption and schedule estimates. Account totals include all owner workspaces; members receive monitor names only from their selected workspace. The requested monitor is retained within the maximum 100 entries. Projection to reset adds the remaining UTC-day fraction of the plan to booked usage. Bursts, events, replay and corrections are not predictable and capacity is not reserved. |
| $ (anyOf 1).forecast.monitors | array<object>; {"maxItems":100} | Yes | — |
| $ (anyOf 1).forecast.monitors[] | object | Yes | One visible monitor. Scheduled rates exclude paused monitors, monitors pending deletion and disabled or archived series. HTTP uses its configured interval, derived series one result per minute, other series their expected interval. Byte estimates use the profile assumptions without heartbeat overhead. |
| $ (anyOf 1).forecast.monitors[].archived | boolean | Yes | — |
| $ (anyOf 1).forecast.monitors[].id | string; {"format":"uuid"} | Yes | — |
| $ (anyOf 1).forecast.monitors[].interval_seconds | integer; {"minimum":10} | null | Yes | — |
| $ (anyOf 1).forecast.monitors[].interval_seconds (anyOf 1) | integer; {"minimum":10} | No | — |
| $ (anyOf 1).forecast.monitors[].interval_seconds (anyOf 2) | null | No | — |
| $ (anyOf 1).forecast.monitors[].name | string | Yes | — |
| $ (anyOf 1).forecast.monitors[].paused | boolean | Yes | — |
| $ (anyOf 1).forecast.monitors[].planned | QuotaDaily | Yes | Data objects include numeric points, states and text events. Events are the state/text subset. Bytes and event bytes are uncompressed charged payload sizes. Planned values are estimates per 24 hours; today values are booked counters. |
| $ (anyOf 1).forecast.monitors[].planned.bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].planned.event_bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].planned.events | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].planned.items | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].profile_planned | QuotaDaily | No | Data objects include numeric points, states and text events. Events are the state/text subset. Bytes and event bytes are uncompressed charged payload sizes. Planned values are estimates per 24 hours; today values are booked counters. |
| $ (anyOf 1).forecast.monitors[].profile_planned.bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].profile_planned.event_bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].profile_planned.events | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].profile_planned.items | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].recorded_from | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).forecast.monitors[].recorded_from (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).forecast.monitors[].recorded_from (anyOf 2) | null | No | — |
| $ (anyOf 1).forecast.monitors[].today | QuotaDaily | Yes | Data objects include numeric points, states and text events. Events are the state/text subset. Bytes and event bytes are uncompressed charged payload sizes. Planned values are estimates per 24 hours; today values are booked counters. |
| $ (anyOf 1).forecast.monitors[].today.bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].today.event_bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].today.events | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].today.items | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.monitors[].type | string | Yes | — |
| $ (anyOf 1).forecast.monitors[].workspace_id | string; {"format":"uuid"} | Yes | — |
| $ (anyOf 1).forecast.other_today | QuotaDaily | Yes | Data objects include numeric points, states and text events. Events are the state/text subset. Bytes and event bytes are uncompressed charged payload sizes. Planned values are estimates per 24 hours; today values are booked counters. |
| $ (anyOf 1).forecast.other_today.bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.other_today.event_bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.other_today.events | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.other_today.items | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.planned | QuotaDaily | Yes | Data objects include numeric points, states and text events. Events are the state/text subset. Bytes and event bytes are uncompressed charged payload sizes. Planned values are estimates per 24 hours; today values are booked counters. |
| $ (anyOf 1).forecast.planned.bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.planned.event_bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.planned.events | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.planned.items | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.reset_at | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 1).forecast.sampled_at | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 1).forecast.truncated | boolean | Yes | — |
| $ (anyOf 1).forecast.workspace_planned | QuotaDaily | Yes | Data objects include numeric points, states and text events. Events are the state/text subset. Bytes and event bytes are uncompressed charged payload sizes. Planned values are estimates per 24 hours; today values are booked counters. |
| $ (anyOf 1).forecast.workspace_planned.bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.workspace_planned.event_bytes | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.workspace_planned.events | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).forecast.workspace_planned.items | number; {"minimum":0} | Yes | — |
| $ (anyOf 1).limit | integer; {"maximum":100,"minimum":1} | No | — |
| $ (anyOf 1).next_cursor | string | No | Cursor for the next matching page; empty when no following page exists. |
| $ (anyOf 1).snapshot | string; {"format":"date-time"} | No | UTC snapshot bound to the cursor; later-created rows do not enter that page sequence. |
| $ (anyOf 1).limit_presentation | array<object> | No | — |
| $ (anyOf 1).limit_presentation[] | object | Yes | — |
| $ (anyOf 1).limit_presentation[].key | string | Yes | — |
| $ (anyOf 1).limit_presentation[].visibility | string; {"enum":["core","contextual","protection"]} | Yes | Presentation class: core allowances, contextual feature allowances, or background protection. Raw limits remain available and enforced. |
| $ (anyOf 1).limit_presentation[].context | string; {"enum":["browser","logs"]} | No | — |
| $ (anyOf 1).series_slots | integer; {"minimum":0} | No | — |
| $ (anyOf 1).copy_counts | null | object | No | — |
| $ (anyOf 1).copy_counts (anyOf 1) | null | No | — |
| $ (anyOf 1).copy_counts (anyOf 2) | object | No | — |
| $ (anyOf 1).copy_counts (anyOf 2).monitors | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).copy_counts (anyOf 2).series | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1) (anyOf 1) | JSON | No | — |
| $ (anyOf 1) (anyOf 2) | JSON | No | — |
| $ (anyOf 2) | object | No | — |
| $ (anyOf 2).filter_counts | TableFilterCounts | Yes | — |
| $ (anyOf 2).filter_counts.field | string | Yes | — |
| $ (anyOf 2).filter_counts.total | integer; {"minimum":0} | Yes | — |
| $ (anyOf 2).filter_counts.values | object | Yes | — |
| $ (anyOf 2).filter_counts.complete | boolean | Yes | — |
| $ (anyOf 2).filter_counts.snapshot | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 2).filter_counts.counted_at | string; {"format":"date-time"} | Yes | — |
{
"active_archive_queries_limit": 2,
"active_exports_limit": 1,
"alarms_limit": 0,
"batch_bytes_limit": 0,
"batch_items_limit": 0,
"bytes_per_minute_limit": 0,
"day_bytes": 0,
"day_bytes_limit": 0,
"day_event_bytes": 0,
"day_event_bytes_limit": 0,
"day_events": 0,
"day_events_limit": 0,
"day_items": 0,
"day_items_limit": 0,
"day_notifications": 0,
"day_points": 0,
"day_points_limit": 0,
"devices": 0,
"devices_limit": 0,
"events_per_minute_limit": 0,
"groups": 2,
"groups_limit": 100,
"items_per_minute_limit": 0,
"keys": 0,
"keys_limit": 0,
"limits": {
"active_alarms": 200,
"active_archive_queries": 2,
"active_devices": 10,
"active_exports": 1,
"active_groups": 100,
"active_keys": 20,
"active_series": 200,
"active_workspaces": 50,
"alarm_per_minute": 10,
"batch_bytes": 262144,
"batch_items": 1000,
"bytes_per_day": 1073741824,
"bytes_per_minute": 2097152,
"device_per_day": 20,
"device_per_minute": 5,
"event_bytes_per_day": 10485760,
"event_per_day": 10000,
"event_per_minute": 60,
"group_per_minute": 10,
"key_per_minute": 5,
"live_series_per_connection": 32,
"notifications_per_day": 500,
"notifications_per_hour": 60,
"point_per_day": 4000000,
"point_per_minute": 3000,
"request_per_minute": 180,
"series_per_30_days": 500,
"series_per_minute": 60,
"workspace_per_minute": 10,
"log_bytes_per_day": 1073741824
},
"limits_version": "0000000000000000000000000000000000000000000000000000000000000000",
"live_series_per_connection_limit": 32,
"monitors": 0,
"monitors_limit": 0,
"new_devices_per_minute_limit": 0,
"new_devices_today": 0,
"new_devices_today_limit": 0,
"new_keys_per_minute_limit": 0,
"new_series_30d": 0,
"new_series_30d_limit": 0,
"new_series_per_minute_limit": 0,
"new_workspaces_per_minute_limit": 0,
"notifications_per_day_limit": 0,
"notifications_per_hour_limit": 0,
"points_per_minute_limit": 0,
"registration_origin": "demo",
"requests_per_minute_limit": 0,
"series": 0,
"series_limit": 0,
"tier": "demo",
"workspaces": 0,
"workspaces_limit": 0,
"forecast": {
"monitors": [],
"other_today": {
"bytes": 0,
"event_bytes": 0,
"events": 0,
"items": 0
},
"planned": {
"bytes": 0,
"event_bytes": 0,
"events": 0,
"items": 0
},
"reset_at": "2026-10-03T00:00:00Z",
"sampled_at": "2026-10-02T12:00:00Z",
"truncated": false,
"workspace_planned": {
"bytes": 0,
"event_bytes": 0,
"events": 0,
"items": 0
}
}
}| Stable error codes |
|---|
| invalid_credential |
| unauthorized |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 401,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| csrf |
| insufficient_scope |
| invalid_origin |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 403,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| unavailable |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Retry-After | string; {"pattern":"^[0-9]+$"} | Seconds before retry. Preserve supported idempotency identifiers and respect the operation’s mutation semantics. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 503,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| invalid_device |
| invalid_input |
| invalid_sort |
| invalid_workspace |
| invalid_copy_source |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 422,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| not_found |
Retries and asynchronous work
This operation reads or validates without applying a resource mutation. Respect rate limits and credential lifetime.
Request examples
Replace demo IDs, timestamps and placeholders with your own values. For a retry, keep the same IDs, time and content. These examples do not run requests on this page.
Keep login links, codes, cookies and keys private. Do not print them in logs or share them in support requests.
curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" \
--request GET \
--header @"$HOME/.config/metribeacon/headers.txt" \
"https://metribeacon.com/api/v1/usage"
import json
from pathlib import Path
from urllib.request import Request, HTTPRedirectHandler, build_opener
from urllib.error import HTTPError
headers = json.loads((Path.home() / ".config/metribeacon/headers.json").read_text())
request = Request("https://metribeacon.com/api/v1/usage", data=None, headers=headers, method="GET")
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, request, fp, code, message, headers, target):
return None
opener = build_opener(NoRedirect())
try:
with opener.open(request, timeout=10) as response:
print(response.status)
except HTTPError as error:
print(error.code)
error.close()
import { readFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";
const headers = JSON.parse(await readFile(join(homedir(), ".config/metribeacon/headers.json"), "utf8"));
const response = await fetch("https://metribeacon.com/api/v1/usage", {
method: "GET", headers, redirect: "manual",
signal: AbortSignal.timeout(10000),
});
console.log(response.status);
await response.body?.cancel();
package main
import (
"fmt"
"net/http"
"time"
"encoding/json"
"os"
"path/filepath"
)
func main() {
home, err := os.UserHomeDir(); if err != nil { panic("request failed; credentials and response omitted") }
raw, err := os.ReadFile(filepath.Join(home, ".config/metribeacon/headers.json")); if err != nil { panic("request failed; credentials and response omitted") }
var headers map[string]string
if json.Unmarshal(raw, &headers) != nil { panic("invalid local headers") }
request, err := http.NewRequest("GET", "https://metribeacon.com/api/v1/usage", nil)
if err != nil { panic("request failed; credentials and response omitted") }
for name, value := range headers { request.Header.Set(name, value) }
client := &http.Client{Timeout: 10*time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
response, err := client.Do(request)
if err != nil { panic("request failed; credentials and response omitted") }
defer response.Body.Close()
fmt.Println(response.StatusCode)
}
Related guides
- HTTP API, OAuth and MCP
Find the user API endpoints, their permissions, fields, examples and response formats.
- GET Get live and history limits
Returns only the effective account limits required for history and live views. With workspace_id, uses the authorized workspace owner’s shared limits. Does not calculate usage or forecasts.
- GET Read currently enabled API capabilities
Read which monitoring features are currently available and which template version to use. Your account's own usage limits still apply.
- GET Read public readiness status
Read public readiness status.