Build a board
A board is a grid of up to 20 tiles, each showing one signal of one monitor: its status, its response time, its uptime or one of its custom metrics. Every person has their own board in each team. A key acts on the board of the team member who created it, in the key's team, so what a key saves is the board that person sees in the app. To build a board for someone else, have them create the key.
Abilities #
GET /board and GET /board/data need board:read, which the read only, read and write, and full presets carry. PUT /board needs board:write, which the read and write and full presets carry. Anonymous workspace keys carry neither. A key keeps the abilities it was created with, so a key made before the board joined the API has neither: create a new key, or a custom one with the board abilities. Authentication covers the presets.
Read the board #
GET /board returns the widgets in display order:
{
"data": [
{
"id": "9d4c2f8a-5b1e-4c7d-8e2f-1a3b5c7d9e0f",
"monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"monitor_metric_id": null,
"source": "response_time",
"view": "chart",
"size": "m",
"range": "24h",
"position": 0,
"monitor": {
"id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"name": "Checkout API"
},
"metric": null
}
]
}
A widget whose monitor was deleted is left out. metric is filled for a metric widget, with the metric's id, key, label, unit and type.
Widget fields #
monitor_idis one of the team's monitors.sourceis the signal:status,response_time,uptimeormetric.monitor_metric_idis a custom metric of that same monitor. Ametricwidget requires it; every other source must leave it out or send null.viewis how the tile renders it:card(one value),chart(a series) orlist(the newest rows).statusanduptimerender ascardonly;response_timeandmetricrender as any of the three. A chart of a metric needs anumericmetric, because a text or status reading has no number to plot.sizeis the tile's footprint:s,morl.rangeis the window the tile reads:24h,7d,30dor90d.
Save the board #
PUT /board replaces the whole list. Send every widget you want to keep, in the order to show them; the array index becomes position. An empty widgets list clears the board.
{
"widgets": [
{
"monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"source": "status",
"view": "card",
"size": "s",
"range": "24h"
},
{
"monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"source": "uptime",
"view": "card",
"size": "s",
"range": "30d"
},
{
"monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"monitor_metric_id": "9d4c2f81-6b7c-4d8e-9f0a-1b2c3d4e5f60",
"source": "metric",
"view": "chart",
"size": "l",
"range": "7d"
}
]
}
The answer is the stored list, in the shape of GET /board. The server mints a new id for every widget on every save, so an id from an earlier read is not kept and an id you send is ignored. Read the ids from the answer before you ask for values.
A 422 stores nothing. It answers when:
- the list holds more than 20 widgets;
- a field is missing or holds a value outside the lists above;
- a monitor is unknown, belongs to another team or was deleted;
- a metric does not belong to its widget's monitor;
- the view is one the source cannot render, or a chart names a metric that is not
numeric.
An unknown monitor and another team's monitor get the same answer.
Read the values #
GET /board/data returns the live values behind the tiles, keyed by widget id. Name the widgets in widgets, a comma-separated list of up to 20 ids (GET /board/data?widgets=<id>,<id>), or leave it out to read every widget. An id that is not on the board is left out of the answer rather than refused.
{
"data": {
"9d4c2f8a-5b1e-4c7d-8e2f-1a3b5c7d9e0f": {
"monitor": {
"status": "active",
"last_status": "up",
"last_checked_at": "2026-11-17T09:59:30+00:00",
"last_response_ms": 182,
"interval_sec": 60
},
"uptime": null,
"latest": null,
"points": [
{
"recorded_at": "2026-11-17T09:00:00+00:00",
"numeric_value": 190,
"band": null
},
{
"recorded_at": "2026-11-17T09:59:30+00:00",
"numeric_value": 182,
"band": null
}
],
"rows": null
}
}
}
Every entry carries monitor: its switch (status, active or paused), its last reading (last_status, last_checked_at, last_response_ms) and interval_sec, the check interval the plan allows. A reading older than twice interval_sec is stale. Of the other four blocks, the widget's source and view fill one and the rest are null:
uptimefor anuptimecard:range,total,up,down,degradedanduptime_ratio(a fraction,0.9921is 99.21%). It is null when the range holds no reading.latestfor ametriccard: the metric's newest reading in the range (recorded_at,numeric_value,string_value,status_value,band), or null when there is none.pointsfor a chart, oldest first, at most 120 points. A longer series is thinned at an even stride and keeps its first and last point. A response time point is a bucket median in milliseconds withbandnull. A metric point is one reading over24h; over a longer range it is a bucket average with the worst band in the bucket.rowsfor a list, newest first, at most 10. A response time row hasrecorded_at,status,status_codeandnumeric_value(the response time in milliseconds); a metric row has the same fields aslatest.
A status card and a response_time card read only monitor, so every other block is null.
How often to poll #
A monitor takes a new reading once per interval_sec, so polling faster shows nothing new. The Uptizm app reads one widget at most once every 15 seconds, and a chart over 7 to 90 days at most once every 10 minutes, since one reading barely moves such a series. Poll at the same pace, and name only the widgets you need in widgets.
Limits #
PUT /board allows 30 saves a minute and GET /board/data 120 reads a minute, per key. Both count against the key's own budget as well; Rate limits has the numbers. On a 429, wait the Retry-After seconds.