Metrics API

The Metrics API is how external systems push live values onto TelemetryOS screens. A metric is a named JSON value — a number, string, table, set, or dictionary — that Metrics apps and dashboard widgets read and redraw as soon as the value changes.

This API is not the User API. Device, playlist, and content automation use the User API (https://api.telemetryos.com). Metric ingest uses a dedicated host:

https://metrics.telemetrytv.com/metrics

The hostname is shared with TelemetryTV. Tokens created in TelemetryOS Studio authenticate the same way.

Authentication

Create a token in Studio under Settings → API Tokens. Send it on every request:

POST /metrics HTTP/1.1
Host: metrics.telemetrytv.com
Authorization: Token YOUR_API_TOKEN
Content-Type: application/json

Treat the token as a secret. Store it in a vault or environment variable, not in source control.

Metrics collection agent

A collection agent is software you run next to your data. It queries a database, spreadsheet, or internal API, turns the result into metrics, and POSTs them to the Metrics API.

Running the agent inside your network means only the derived values leave the firewall. The rest of the source data never has to be reachable from the internet.

Any language that can make an HTTPS POST is fine. Google Apps Script, a Python cron job, and a small Node service are all common patterns.

Metric keys

Every metric has a key. In the JSON body the key must start with $. That prefix is how the API tells a metric apart from optional parameters such as range or folder.

Valid key characters after $: a-z, 0-9, -, ., _, |. Length is 1–32 characters (not counting $).

{"$queue_depth": 42}

Optional parameters

These fields sit alongside $keys in the same object. When several metrics share one object, the parameters apply to all of them. Use a JSON array of objects when metrics need different parameters.

Number metrics with a bucket keep last, average, min, and max for each interval and drop the raw samples. Other kinds do not keep history.

Metric kinds

The JSON type of the $key value selects the kind. Widgets expect matching kinds.

Number

Integer or float. Used by number, gauge, and (with a bucket) line-chart widgets.

{"$mynumber": 902}

Text

A string. Text widgets accept a small markup set for color, size, bold, italic, and underline.

{"$mytext": "Hello World"}
{"$big_red_text": "{red|(extra-large|Hello World)}"}

Set

An array of strings or numbers. Line charts can plot a set as equally spaced points.

{"$myset": ["Alpha", "Bravo", "Charlie"]}

Table

An array of arrays (rows, then cells). Table, bar-chart, and leaderboard widgets use this shape.

{"$mytable": [["Row1Col1", "Row1Col2"], ["Row2Col1", "Row2Col2"]]}

Dictionary

An object of keys to numbers or strings. Pie charts use dictionaries as labeled slices.

{"$mydictionary": {"alpha": 1, "bravo": 2, "charlie": 3}}

Request shapes

Single metric:

{"$mymetric": 100}

Several metrics, same parameters:

{"$customers": 77, "$users": 23, "range": 20}

Batch with different parameters:

[{"$customers": 77, "range": 20}, {"$users": 23, "range": 30}]

Example

curl -X POST "https://metrics.telemetrytv.com/metrics" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"$queue_depth": 42, "folder": "operations", "bucket": "hour", "range": 24}'

A 200 response returns the stored metric record (id, kind, value, bucket fields, timestamps). A 400 response means the body could not be parsed or a key/parameter was invalid.

Related

• Submit a metric — OpenAPI for POST /metrics
• User API — devices, playlists, content, and webhooks
• API Tokens