GET Live monitor and server lists
/api/v1/devices/live
Live monitor or server list for browser sessions only. Uses the same filters and page as getDevices, including empty selections. devices events contain the complete page, status counts and facets; access_revoked clears private data, invalidated requires reloading the page. Shared streams refresh within five seconds while connected and pause in background tabs.
On this page
Access and permissions
Live monitor or server list for browser sessions only. Uses the same filters and page as getDevices, including empty selections. devices events contain the complete page, status counts and facets; access_revoked clears private data, invalidated requires reloading the page. Shared streams refresh within five seconds while connected and pause in background tabs.
Browser session: __Host-mb_session cookie.
Parameters and headers
| Field | Location | Type and limits | Required | Meaning |
|---|---|---|---|---|
| workspace_id | URL query | string; {"format":"uuid"} | Yes | UUID of an owned workspace. When optional, omission selects the documented default or all owned workspaces. |
| q | URL query | string; {"maxLength":128} | No | Search names, UUIDs and safe website origins or host/port targets. Credentials, URL paths and query secrets are excluded. |
| group_id | URL query | string; {"format":"uuid"} | JSON; {"const":"none"} | No | Filter by membership in this active group; none means no active group memberships. |
| type | URL query | string; {"default":"","enum":["","custom","server","http","job","workflow","sensor","application","ai_agent","industrial","tcp","udp","dns","tls","ping","service","browser"]} | No | Filter by monitor type. Omit this parameter or leave it empty to include all types. |
| state | URL query | string; {"default":"all","enum":["all","fresh","missing","attention","paused","up","down","unknown","warn"]} | No | Monitor state. warn selects monitors with open alarms, excluding paused monitors; up and down independently describe confirmed reachability. |
| sort | URL query | string; {"default":"newest","enum":["newest","oldest","name_asc","name_desc","manual"]} | No | Use 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. |
| limit | URL query | integer; {"default":50,"maximum":100,"minimum":1} | No | Maximum number of returned rows; use the operation-specific default and upper bound. |
| cursor | URL query | string; {"maxLength":4096} | No | Bound to the account and filters; valid for 15 minutes |
| include_summary | URL query | boolean; {"default":false} | No | Include 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_group | URL query | string; {"enum":["all","monitors","servers"],"default":"all"} | No | Filter by Monitors or Servers before counts and pagination. Omit the filter or use all for the complete list. Cursors are bound to this selection. |
| types | URL query | string; {"maxLength":2048} | No | Comma-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_ids | URL query | string; {"maxLength":2048} | No | Comma-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_ids | URL query | string; {"maxLength":2048} | No | Comma-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_facets | URL query | boolean; {"default":false} | No | Include 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_order | URL query | boolean; {"default":false} | No | For 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. |
Request body
No request body.
Responses
| Stable error codes |
|---|
| unauthorized |
| invalid_credential |
| session_revoked |
| 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 |
|---|
| browser_session_required |
| csrf |
| insufficient_scope |
| invalid_origin |
| workspace_scope |
| 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 |
|---|
| not_found |
| 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": 404,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| invalid_cursor |
| invalid_filters |
| invalid_live |
| invalid_selection |
| live_limit |
| 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 |
|---|
| feature_unavailable |
| stream_unavailable |
| 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 |
|---|
| feature_unavailable |
| unavailable |
| live_capacity |
| 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"
}text/event-stream
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | string | Yes | — |
event: devices
data: {"workspace_id":"00000000-0000-4000-8000-000000000001","devices":[],"observed_at":"2026-10-15T12:00:00Z","status_counts":{"all":0,"up":0,"down":0},"total_count":0,"matched_count":0,"facets":{"types":[],"group_ids":[],"location_ids":[],"state":[]},"next_cursor":"","snapshot":"2026-10-15T12:00:00Z","limit":50}
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/devices/live?workspace_id=00000000-0000-4000-8000-000000000001&list_group=servers&include_facets=true&include_summary=true"
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/live?workspace_id=00000000-0000-4000-8000-000000000001&list_group=servers&include_facets=true&include_summary=true", 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/devices/live?workspace_id=00000000-0000-4000-8000-000000000001&list_group=servers&include_facets=true&include_summary=true", {
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/devices/live?workspace_id=00000000-0000-4000-8000-000000000001&list_group=servers&include_facets=true&include_summary=true", 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 Search and page through devices in your workspace
Search and page through devices in your workspace.
- POST Create a device
Create a device.
- GET Read your active device
Read your active device.