Send your own monitoring data

Prepare your monitor

1. Create a monitor and a Gauge series, then create a key for that monitor. Store it in a private file readable only by you (0600).
2. Copy the series UUID. Create a batch UUID and a point UUID for each reading. Use its actual UTC timestamp.
3. For retries, keep these IDs, timestamps and values unchanged.

Send one reading

Replace SERIES_UUID below with your own series ID. The example creates fresh IDs and the current timestamp. It reads the key privately and keeps it out of curl's command arguments.

export METRIBEACON_SERIES="SERIES_UUID"
python3 - <<'PY' > batch.json
import datetime, json, os, uuid
print(json.dumps({"batch_id": str(uuid.uuid4()), "points": [{
    "id": str(uuid.uuid4()), "series_id": os.environ["METRIBEACON_SERIES"],
    "measured_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
    "value": 42.5}]}))
PY
METRIBEACON_KEY=$(cat "$HOME/.config/metribeacon/device.key")
printf 'header = "Authorization: Bearer %s"\n' "$METRIBEACON_KEY" | \
  curl --config - --fail-with-body --request POST \
  https://metribeacon.com/api/v1/ingest/points \
  --header "Content-Type: application/json" --data-binary @batch.json
unset METRIBEACON_KEY

Check the response

accepted counts newly stored readings; duplicates counts identical readings already received. An older reading can appear in history without replacing a newer current value. The response below is an example, not the result of a live request.

{"batch_id":"11111111-1111-4111-8111-111111111111", "accepted":1, "duplicates":0}

Request limits

A batch may contain up to 1,000 items and 256 KiB, both before and after gzip decompression. Numerical readings of one series must be at least one second apart. Readings may be up to 24 hours old or two minutes ahead. Your account's usage limits also apply.

Retry safely

For 429 or temporary 503 errors, wait for Retry-After and retry the same prepared batch. Fix key or access problems for 401/403, reduce size for 413 and correct data for 422. Use code for automation and request_id for help.

States and events

Use /api/v1/ingest/states for Boolean or Enum readings and /api/v1/ingest/events for short messages. They share your data allowance and also have a smaller event allowance. The API reference provides the complete fields and examples.