Skip to content
Uptizm
Sign in
Menu
View as Markdown

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_id is one of the team's monitors.
  • source is the signal: status, response_time, uptime or metric.
  • monitor_metric_id is a custom metric of that same monitor. A metric widget requires it; every other source must leave it out or send null.
  • view is how the tile renders it: card (one value), chart (a series) or list (the newest rows). status and uptime render as card only; response_time and metric render as any of the three. A chart of a metric needs a numeric metric, because a text or status reading has no number to plot.
  • size is the tile's footprint: s, m or l.
  • range is the window the tile reads: 24h, 7d, 30d or 90d.

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:

  • uptime for an uptime card: range, total, up, down, degraded and uptime_ratio (a fraction, 0.9921 is 99.21%). It is null when the range holds no reading.
  • latest for a metric card: the metric's newest reading in the range (recorded_at, numeric_value, string_value, status_value, band), or null when there is none.
  • points for 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 with band null. A metric point is one reading over 24h; over a longer range it is a bucket average with the worst band in the bucket.
  • rows for a list, newest first, at most 10. A response time row has recorded_at, status, status_code and numeric_value (the response time in milliseconds); a metric row has the same fields as latest.

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.

Type to search the guides, resources and endpoints.