---
title: "Rolling telemetry history in 5-minute buckets (host owner/admin)"
method: GET
path: "/api/v1/hosts/machines/{id}/telemetry"
tags: ["hosts"]
---

# Rolling telemetry history in 5-minute buckets (host owner/admin)

`GET /api/v1/hosts/machines/{id}/telemetry`

## Request

- Base URL: `https://amplerun-api.spiry.org`
- URL: `https://amplerun-api.spiry.org/api/v1/hosts/machines/{id}/telemetry`
- Auth: HTTP bearer

Min/avg/max per measured field per 5-minute bucket, for sparklines. Host owner only: a non-owner receives 404, never 403, so machine existence never leaks. History is retained for 48 h and pruned by the worker cleanup task; a `window` longer than the retention is refused rather than silently clamped. A field that was never measured in a bucket is absent, and a bucket's `samples` count states how much evidence backs it.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `window` string

## Response `200`

Telemetry history buckets, oldest first.

- object
  - `machine_id` string, uuid, required
  - `window_s` integer, required
  - `bucket_s` 300, required
  - `retention_s` 172800, required
  - `buckets` object[], required
    - `bucket` string, date-time, required
    - `samples` integer, required
    - `devices` object[], required
      - `pci_address` string, required
      - `temperature_c` TelemetryNumberSummary: Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.
        - `min` number, required
        - `avg` number, required
        - `max` number, required
      - `utilization_pct` TelemetryNumberSummary: Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.
        - `min` number, required
        - `avg` number, required
        - `max` number, required
      - `power_watts` TelemetryNumberSummary: Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.
        - `min` number, required
        - `avg` number, required
        - `max` number, required
      - `fan_pct` TelemetryNumberSummary: Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.
        - `min` number, required
        - `avg` number, required
        - `max` number, required
      - `memory_used_bytes` TelemetryAmountSummary: Min/avg/max of one measured byte/second counter within a 5-minute bucket, as exact decimal strings (avg is floored; a byte count is never a float).
        - `min` string, required: Unsigned base-10 integer as string; never a float.
        - `avg` string, required: Unsigned base-10 integer as string; never a float.
        - `max` string, required: Unsigned base-10 integer as string; never a float.
      - `unified_memory_used_bytes` TelemetryAmountSummary: Min/avg/max of one measured byte/second counter within a 5-minute bucket, as exact decimal strings (avg is floored; a byte count is never a float).
        - `min` string, required: Unsigned base-10 integer as string; never a float.
        - `avg` string, required: Unsigned base-10 integer as string; never a float.
        - `max` string, required: Unsigned base-10 integer as string; never a float.
    - `host` object
      - `cpu_utilization_pct` TelemetryNumberSummary: Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.
        - `min` number, required
        - `avg` number, required
        - `max` number, required
      - `load1` TelemetryNumberSummary: Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.
        - `min` number, required
        - `avg` number, required
        - `max` number, required
      - `memory_used_bytes` TelemetryAmountSummary: Min/avg/max of one measured byte/second counter within a 5-minute bucket, as exact decimal strings (avg is floored; a byte count is never a float).
        - `min` string, required: Unsigned base-10 integer as string; never a float.
        - `avg` string, required: Unsigned base-10 integer as string; never a float.
        - `max` string, required: Unsigned base-10 integer as string; never a float.
      - `disk_free_bytes` TelemetryAmountSummary: Min/avg/max of one measured byte/second counter within a 5-minute bucket, as exact decimal strings (avg is floored; a byte count is never a float).
        - `min` string, required: Unsigned base-10 integer as string; never a float.
        - `avg` string, required: Unsigned base-10 integer as string; never a float.
        - `max` string, required: Unsigned base-10 integer as string; never a float.
      - `uptime_s` TelemetryAmountSummary: Min/avg/max of one measured byte/second counter within a 5-minute bucket, as exact decimal strings (avg is floored; a byte count is never a float).
        - `min` string, required: Unsigned base-10 integer as string; never a float.
        - `avg` string, required: Unsigned base-10 integer as string; never a float.
        - `max` string, required: Unsigned base-10 integer as string; never a float.

## Other responses

- `default`: Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.

---

[API](https://skmtc.dev/amplerun/apis/amplerun-business-api.md) · [All operations](https://skmtc.dev/amplerun/apis/amplerun-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/amplerun/apis/amplerun-business-api/revisions/40944687fa52?raw)