MetriBeacon
Menu

GET Search and page through devices in your workspace

/api/v1/devices

Search and page through devices in your workspace.

On this page

Access and permissions

Search and page through devices in your workspace.

Browser session: __Host-mb_session cookie.

Machine management credentials in Authorization: Bearer. Check the permissions (scopes) required by the operation.

Parameters and headers

FieldLocationType and limitsRequiredMeaning
workspace_idURL querystring; {"format":"uuid"}YesUUID of an owned workspace. When optional, omission selects the documented default or all owned workspaces.
qURL querystring; {"maxLength":128}NoSearch names, UUIDs and safe website origins or host/port targets. Credentials, URL paths and query secrets are excluded.
group_idURL querystring; {"format":"uuid"} | JSON; {"const":"none"}NoFilter by membership in this active group; none means no active group memberships.
typeURL querystring; {"default":"","enum":["","custom","server","http","job","workflow","sensor","application","ai_agent","industrial","tcp","udp","dns","tls","ping","service","browser"]}NoFilter by monitor type. Omit this parameter or leave it empty to include all types.
stateURL querystring; {"default":"all","enum":["all","fresh","missing","attention","paused","up","down","unknown","warn"]}NoMonitor state. warn selects monitors with open alarms, excluding paused monitors; up and down independently describe confirmed reachability.
sortURL querystring; {"default":"newest","enum":["newest","oldest","name_asc","name_desc","manual"]}NoUse manual with list_group=monitors or servers to read your personal order. Manual cursors also bind the acting user and order revision; stale cursors return 422. Other sort modes keep their existing behavior.
limitURL queryinteger; {"default":50,"maximum":100,"minimum":1}NoMaximum number of returned rows; use the operation-specific default and upper bound.
cursorURL querystring; {"maxLength":4096}NoBound to the account and filters; valid for 15 minutes
include_summaryURL queryboolean; {"default":false}NoInclude up to three automatically selected metrics for each returned monitor. Values include timestamps, validity and source information. Missing or outdated data is explicitly identified; this option does not start checks. Machine and MCP/OAuth access additionally requires telemetry:read. With this option, limit must not exceed 50.
list_groupURL querystring; {"enum":["all","monitors","servers"],"default":"all"}NoFilter by Monitors or Servers before counts and pagination. Omit the filter or use all for the complete list. Cursors are bound to this selection.
typesURL querystring; {"maxLength":2048}NoComma-separated selection of up to 50 values. Values within a category match with OR; categories combine with AND. Do not combine with a conflicting singular filter. Group none selects ungrouped monitors. Locations refer to configured assignments, including unavailable locations.
group_idsURL querystring; {"maxLength":2048}NoComma-separated selection of up to 50 values. Values within a category match with OR; categories combine with AND. Do not combine with a conflicting singular filter. Group none selects ungrouped monitors. Locations refer to configured assignments, including unavailable locations.
location_idsURL querystring; {"maxLength":2048}NoComma-separated selection of up to 50 values. Values within a category match with OR; categories combine with AND. Do not combine with a conflicting singular filter. Group none selects ungrouped monitors. Locations refer to configured assignments, including unavailable locations.
include_facetsURL queryboolean; {"default":false}NoInclude list-wide totals, Up/Down counts and filter values before pagination (maximum 50 rows). Status counts ignore the state selection; each facet ignores its own category. Up/Down follow confirmed check, run or contact status, independently of open alarms. Paused and unknown checks are neither Up nor Down.
personal_orderURL queryboolean; {"default":false}NoFor browser monitor and server lists, include the personal order revision and resolve an omitted sort to the saved personal order or newest first. Explicit sorting is preserved.
viewURL querystring; {"enum":["options"]}NoSet options for a bounded metadata-only monitor selector. Searches names and monitor IDs, uses name order, accepts at most 50 rows per page, and does not support summary, facets, personal order, state, group or location filters.
counts_onlyURL querystring; {"enum":["1"]}NoReturn counts for the requested filter instead of table rows. Counts include search and other filters, excluding this filter selection, sorting and pagination.
count_filterURL querystring; {"enum":["state"]}NoDeclared table filter to count. Requires counts_only=1.
snapshotURL querystring; {"format":"date-time"}NoOptional snapshot from the corresponding table page.

Request body

No request body.

Responses

HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"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-PolicyJSON; {"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.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/json

FieldType and limitsRequiredMeaning
$object | objectYes—
$ (anyOf 1)objectNo—
$ (anyOf 1).devicesarray<object>Yes—
$ (anyOf 1).devices[]objectYes—
$ (anyOf 1).devices[].attentionbooleanYes—
$ (anyOf 1).devices[].created_atstring; {"format":"date-time"}YesCreation timestamp in RFC 3339 UTC.
$ (anyOf 1).devices[].group_idsarray<string; {"format":"uuid"}>YesIDs of active groups containing this device, or an empty array.
$ (anyOf 1).devices[].group_ids[]string; {"format":"uuid"}Yes—
$ (anyOf 1).devices[].http_checked_atstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].http_checked_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].http_checked_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].http_statusstring | nullYes—
$ (anyOf 1).devices[].http_status (anyOf 1)stringNo—
$ (anyOf 1).devices[].http_status (anyOf 2)nullNo—
$ (anyOf 1).devices[].idstringYesUUID of this resource. Keep the returned identifier for subsequent operations.
$ (anyOf 1).devices[].last_heartbeat_atstring; {"format":"date-time"} | nullYesLast accepted device contact timestamp; null before the first contact.
$ (anyOf 1).devices[].last_heartbeat_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].last_heartbeat_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].monitor_typestringYes—
$ (anyOf 1).devices[].namestringYesHuman-readable resource name. Follow the listed length limit.
$ (anyOf 1).devices[].pausedbooleanYesWhether automatic monitor work is paused. Existing telemetry and historical data remain.
$ (anyOf 1).devices[].workspace_idstringYesUUID of the owning workspace. Access is checked against the authenticated account.
$ (anyOf 1).devices[].check_resultobject; {"additionalProperties":false}NoOptional evaluated check result or latest retained run. Checks use the configured location policy, current node capability and valid observations. Unknown or stale evidence is not a passed check. Run outcomes describe the latest retained execution, not a service health guarantee.
$ (anyOf 1).devices[].check_result.statusstring; {"enum":["up","down","unknown","paused","succeeded","failed","running","missing","overdue","cancelled"]}Yes—
$ (anyOf 1).devices[].check_result.checked_atstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].check_result.checked_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].check_result.checked_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].check_result.freshnessstring; {"enum":["current","stale","missing"]}Yes—
$ (anyOf 1).devices[].check_result.valid_untilstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].check_result.valid_until (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].check_result.valid_until (anyOf 2)nullNo—
$ (anyOf 1).devices[].summaryMonitorListSummaryNoOptional metrics for this page only: stable IDs, values, units, freshness and source timestamps. Missing preferred metrics use current recorded alternatives; existing stale values remain visible. State groups distinguish confirmed yes, confirmed no and sources without a current value. A replacement identifies the missing metric and its reason. No additional collection is enabled.
$ (anyOf 1).devices[].summary.attention_reasonsarray<string; {"maxLength":128}>; {"maxItems":8}NoNames of up to eight unresolved alarms, critical alarms first. Includes acknowledged alarms and excludes archived rules.
$ (anyOf 1).devices[].summary.attention_reasons[]string; {"maxLength":128}Yes—
$ (anyOf 1).devices[].summary.attention_countinteger; {"minimum":0}NoTotal number of unresolved alarms represented by the monitor warning.
$ (anyOf 1).devices[].summary.statusstring; {"enum":["available","unavailable"]}Yes—
$ (anyOf 1).devices[].summary.targetstringYes—
$ (anyOf 1).devices[].summary.systemstringYes—
$ (anyOf 1).devices[].summary.interval_secondsinteger; {"minimum":0}Yes—
$ (anyOf 1).devices[].summary.metricsarray<object; {"additionalProperties":false}>; {"maxItems":3}Yes—
$ (anyOf 1).devices[].summary.metrics[]object; {"additionalProperties":false}Yes—
$ (anyOf 1).devices[].summary.metrics[].keystringYes—
$ (anyOf 1).devices[].summary.metrics[].valuenumber | string | nullYes—
$ (anyOf 1).devices[].summary.metrics[].unitstringYes—
$ (anyOf 1).devices[].summary.metrics[].freshnessstring; {"enum":["fresh","stale","missing","reported","scheduled"]}Yes—
$ (anyOf 1).devices[].summary.metrics[].reasonstringNo—
$ (anyOf 1).devices[].summary.metrics[].measured_atstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].summary.metrics[].measured_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].summary.metrics[].measured_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].summary.metrics[].valid_untilstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].summary.metrics[].valid_until (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].summary.metrics[].valid_until (anyOf 2)nullNo—
$ (anyOf 1).devices[].summary.metrics[].sourcesarray<object; {"additionalProperties":false}>Yes—
$ (anyOf 1).devices[].summary.metrics[].sources[]object; {"additionalProperties":false}Yes—
$ (anyOf 1).devices[].summary.metrics[].usednumberNo—
$ (anyOf 1).devices[].summary.metrics[].totalnumberNo—
$ (anyOf 1).devices[].summary.metrics[].coresnumberNo—
$ (anyOf 1).devices[].summary.metrics[].pathstringNo—
$ (anyOf 1).devices[].summary.metrics[].enginestringNo—
$ (anyOf 1).devices[].summary.metrics[].configuredinteger; {"minimum":0}No—
$ (anyOf 1).devices[].summary.metrics[].idstringYes—
$ (anyOf 1).devices[].summary.metrics[].label_keystringNo—
$ (anyOf 1).devices[].summary.metrics[].namestringNo—
$ (anyOf 1).devices[].summary.metrics[].componentstringNo—
$ (anyOf 1).devices[].summary.metrics[].kindstring; {"enum":["gauge","counter","boolean","enum"]}No—
$ (anyOf 1).devices[].summary.metrics[].aggregationstring; {"enum":["mean","min"]}No—
$ (anyOf 1).devices[].summary.metrics[].replacesobject; {"additionalProperties":false}No—
$ (anyOf 1).devices[].summary.metrics[].replaces.keystringYes—
$ (anyOf 1).devices[].summary.metrics[].replaces.reasonstringYes—
$ (anyOf 1).devices[].summary.metrics[].groupobject; {"additionalProperties":false}No—
$ (anyOf 1).devices[].summary.metrics[].group.totalinteger; {"minimum":0}Yes—
$ (anyOf 1).devices[].summary.metrics[].group.positiveinteger; {"minimum":0}Yes—
$ (anyOf 1).devices[].summary.metrics[].group.negativeinteger; {"minimum":0}Yes—
$ (anyOf 1).devices[].summary.metrics[].group.unknowninteger; {"minimum":0}Yes—
$ (anyOf 1).devices[].summary.favicon_urlstringNoRelative, authenticated image URL for the favicon of an HTTP or browser monitor.
$ (anyOf 1).devices[].summary.location_countinteger; {"minimum":0}Yes—
$ (anyOf 1).devices[].summary.platformstring; {"enum":["linux","darwin","windows"]}NoAgent-reported operating system. Omitted when it is unknown.
$ (anyOf 1).devices[].summary.last_value_received_atstring; {"format":"date-time"} | nullNoReceipt time of the latest retained original numeric or state value across active series. Excludes heartbeats, text events, disabled series and derived calculations. Null when no such value is available.
$ (anyOf 1).devices[].summary.last_value_received_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].summary.last_value_received_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].summary.agent_updateAgentUpdateInfoNo—
$ (anyOf 1).devices[].summary.agent_update.operating_systemstringYes—
$ (anyOf 1).devices[].summary.agent_update.installed_versionstringYes—
$ (anyOf 1).devices[].summary.agent_update.latest_versionstringYes—
$ (anyOf 1).devices[].summary.agent_update.statestring; {"enum":["unknown","current","update_available"]}Yes—
$ (anyOf 1).devices[].summary.agent_update.reasonstringYes—
$ (anyOf 1).devices[].summary.agent_update.can_updatebooleanYes—
$ (anyOf 1).devices[].summary.agent_update.target_idstringYes—
$ (anyOf 1).devices[].summary.agent_update.jobAgentUpdateJobNo—
$ (anyOf 1).devices[].summary.agent_update.job.idstring; {"format":"uuid"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.installation_idstring; {"pattern":"^[0-9a-f]{32}$"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.statestring; {"enum":["pending","running","succeeded","failed","expired","unconfirmed"]}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.phasestring; {"enum":["downloading","installing","restarting","completed"]}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.targetAgentUpdateTargetYes—
$ (anyOf 1).devices[].summary.agent_update.job.target.commitstring; {"pattern":"^[0-9a-f]{40}$"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.target.versionstringYes—
$ (anyOf 1).devices[].summary.agent_update.job.target.created_atstring; {"format":"date-time"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.target.fileobject; {"additionalProperties":false}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.requested_atstring; {"format":"date-time"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.updated_atstring; {"format":"date-time"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.claimed_atstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].summary.agent_update.job.claimed_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].summary.agent_update.job.claimed_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].summary.agent_update.job.finished_atstring; {"format":"date-time"} | nullYes—
$ (anyOf 1).devices[].summary.agent_update.job.finished_at (anyOf 1)string; {"format":"date-time"}No—
$ (anyOf 1).devices[].summary.agent_update.job.finished_at (anyOf 2)nullNo—
$ (anyOf 1).devices[].summary.agent_update.job.error_codestringYes—
$ (anyOf 1).devices[].summary.agent_update.job.monitor_idstring; {"format":"uuid"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.operation_idstring; {"format":"uuid"}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.source_versionstring; {"maxLength":128}Yes—
$ (anyOf 1).devices[].summary.agent_update.job.source_sha256string; {"pattern":"^[0-9a-f]{64}$"}Yes—
$ (anyOf 1).devices[].list_groupstring; {"enum":["monitors","servers"]}YesEffective list: server profiles always use servers; checks and scheduled runs use monitors. Other data sources use the explicit choice or confirmed native-agent detection.
$ (anyOf 1).devices[].health_statestring; {"enum":["up","down","unknown","paused"]}No—
$ (anyOf 1).limitintegerYesMaximum number of returned entries within the documented bounds.
$ (anyOf 1).next_cursorstringYesCursor for the next page; null or empty, as specified by the schema, means the current list has ended.
$ (anyOf 1).snapshotstringYes—
$ (anyOf 1).countsobject; {"additionalProperties":false}NoCounts for the entire matching filter selection before cursor pagination. Current means a valid check result, retained run outcome or server contact; it does not prove all services healthy. Attention can overlap unknown results.
$ (anyOf 1).counts.totalinteger; {"minimum":0}Yes—
$ (anyOf 1).counts.currentinteger; {"minimum":0}Yes—
$ (anyOf 1).counts.attentioninteger; {"minimum":0}Yes—
$ (anyOf 1).counts.unknowninteger; {"minimum":0}Yes—
$ (anyOf 1).counts.pausedinteger; {"minimum":0}Yes—
$ (anyOf 1).order_revisioninteger; {"minimum":0}NoCurrent order revision. Supply it as expected_revision when moving or resetting; another change returns 409.
$ (anyOf 1).total_countinteger; {"minimum":0}No—
$ (anyOf 1).matched_countinteger; {"minimum":0}No—
$ (anyOf 1).workspace_idstring; {"format":"uuid"}No—
$ (anyOf 1).observed_atstring; {"format":"date-time"}No—
$ (anyOf 1).status_countsobjectNo—
$ (anyOf 1).status_counts.allinteger; {"minimum":0}Yes—
$ (anyOf 1).status_counts.upinteger; {"minimum":0}Yes—
$ (anyOf 1).status_counts.warninteger; {"minimum":0}NoNumber of distinct unpaused monitors with open alarms, across all matching resources before pagination. Independent of up and down counts.
$ (anyOf 1).status_counts.downinteger; {"minimum":0}Yes—
$ (anyOf 1).status_counts.unknowninteger; {"minimum":0}No—
$ (anyOf 1).status_counts.pausedinteger; {"minimum":0}No—
$ (anyOf 1).facetsobjectNo—
$ (anyOf 1).facets.typesarray<object>No—
$ (anyOf 1).facets.types[]objectYes—
$ (anyOf 1).facets.types[].valuestringYes—
$ (anyOf 1).facets.types[].labelstringNo—
$ (anyOf 1).facets.types[].countinteger; {"minimum":0}Yes—
$ (anyOf 1).facets.group_idsarray<object>No—
$ (anyOf 1).facets.group_ids[]objectYes—
$ (anyOf 1).facets.group_ids[].valuestringYes—
$ (anyOf 1).facets.group_ids[].labelstringNo—
$ (anyOf 1).facets.group_ids[].countinteger; {"minimum":0}Yes—
$ (anyOf 1).facets.location_idsarray<object>No—
$ (anyOf 1).facets.location_ids[]objectYes—
$ (anyOf 1).facets.location_ids[].valuestringYes—
$ (anyOf 1).facets.location_ids[].labelstringNo—
$ (anyOf 1).facets.location_ids[].countinteger; {"minimum":0}Yes—
$ (anyOf 1).facets.statearray<object>No—
$ (anyOf 1).facets.state[]objectYes—
$ (anyOf 1).facets.state[].valuestringYes—
$ (anyOf 1).facets.state[].labelstringNo—
$ (anyOf 1).facets.state[].countinteger; {"minimum":0}Yes—
$ (anyOf 1).has_custom_orderbooleanNo—
$ (anyOf 1).resolved_sortstring; {"enum":["newest","oldest","name_asc","name_desc","manual"]}No—
$ (anyOf 2)objectNo—
$ (anyOf 2).filter_countsTableFilterCountsYes—
$ (anyOf 2).filter_counts.fieldstringYes—
$ (anyOf 2).filter_counts.totalinteger; {"minimum":0}Yes—
$ (anyOf 2).filter_counts.valuesobjectYes—
$ (anyOf 2).filter_counts.completebooleanYes—
$ (anyOf 2).filter_counts.snapshotstring; {"format":"date-time"}Yes—
$ (anyOf 2).filter_counts.counted_atstring; {"format":"date-time"}Yes—
json
{
  "devices": [],
  "limit": 0,
  "next_cursor": "demo",
  "snapshot": "demo"
}
Stable error codes
invalid_credential
invalid_token
unauthorized
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"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-PolicyJSON; {"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.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
json
{
  "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
browser_session_required
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"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-PolicyJSON; {"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.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
json
{
  "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
not_found
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"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-PolicyJSON; {"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.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
json
{
  "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": 404,
  "title": "Demo error",
  "type": "about:blank"
}
Stable error codes
invalid_cursor
invalid_filter
invalid_filters
invalid_limit
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"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-PolicyJSON; {"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.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
json
{
  "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
unavailable
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"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-PolicyJSON; {"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-Afterstring; {"pattern":"^[0-9]+$"}Seconds before retry. Preserve supported idempotency identifiers and respect the operation’s mutation semantics.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
json
{
  "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"
}

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.

shell
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/devices?workspace_id=00000000-0000-4000-8000-000000000001"
python
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/devices?workspace_id=00000000-0000-4000-8000-000000000001", 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()
javascript
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/devices?workspace_id=00000000-0000-4000-8000-000000000001", {
  method: "GET", headers, redirect: "manual",
  signal: AbortSignal.timeout(10000),
});
console.log(response.status);
await response.body?.cancel();
go
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/devices?workspace_id=00000000-0000-4000-8000-000000000001", 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)
}