Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. OpenTelemetry
    3. Vector
    4. Ingesting via HTTP API
    5. Ingesting metrics
    6. Ingesting logs
    7. Migrating to Better Stack
  5. Using the product
    1. AI SRE ↗
    2. MCP server ↗
    3. Transforming ingested data
    4. Querying data
    5. Tracing
    6. Grafana
    7. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources & collectors
      1. Sources API
      2. Collectors API
        1. List all collectors GET
        2. Get a single collector GET
        3. Create a collector POST
        4. Update a collector PATCH
        5. Remove a collector DELETE
        6. List hosts where a collector is running GET
        7. Lists databases monitored by a collector GET
      3. Collector metrics targets API
      4. Metrics API
      5. Source groups API
    3. Dashboards
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
    8. Usage API ↗
  7. Alternative to
    1. Lightstep

List hosts where a collector is running

Returns a list of hosts where the specified collector is running.

GET https://telemetry.betterstack.com/api/v1/collectors/{id}/hosts

URL parameters

id
required string

The unique identifier of the collector.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the collector's hosts.

Response body

{
  "data": [
    {
      "id": "101",
      "type": "collector_host",
      "attributes": {
        "hostname": "k8s-node-1.example.com",
        "status": "up",
        "collector_version": "0.1.0",
        "pinged_at": "2023-10-27T10:05:00.000Z",
        "first_pinged_at": "2023-10-26T10:01:00.000Z",
        "last_error": "",
        "installed_as": "kubernetes",
        "system_information": {
          "ebpf_supported": true,
          "kernel_version": "6.1.0-18-amd64",
          "ring_buffer_supported": true,
          "bpf_filesystem_mounted": true,
          "btf_support_available": true,
          "bpf_syscall_enabled": true,
          "bpf_jit_enabled": true,
          "uprobes_available": true,
          "kprobes_available": true,
          "kernel_lockdown": null,
          "fionread_regression_kernel": false,
          "architecture": "x86_64",
          "distribution": "Debian GNU/Linux 12 (bookworm)"
        }
      }
    },
    {
      "id": "102",
      "type": "collector_host",
      "attributes": {
        "hostname": "k8s-node-2.example.com",
        "status": "down",
        "collector_version": "0.1.0",
        "pinged_at": "2023-10-27T09:00:00.000Z",
        "first_pinged_at": "2023-10-26T10:02:00.000Z",
        "last_error": "",
        "installed_as": "kubernetes",
        "system_information": {
          "ebpf_supported": true,
          "kernel_version": "6.1.0-18-amd64",
          "ring_buffer_supported": true,
          "bpf_filesystem_mounted": true,
          "btf_support_available": true,
          "bpf_syscall_enabled": true,
          "bpf_jit_enabled": true,
          "uprobes_available": true,
          "kprobes_available": true,
          "kernel_lockdown": null,
          "fionread_regression_kernel": false,
          "architecture": "x86_64",
          "distribution": "Debian GNU/Linux 12 (bookworm)"
        }
      }
    }
  ]
}
401

Invalid or missing authentication token.

404

A collector with the specified ID was not found.

Response attributes

id
string

The ID of the host.

type
string

Always collector_host.

attributes.hostname
string

The hostname the host reported.

attributes.status
string

The host's status, one of pending, up, degraded, unknown or down, where down means no ping in the last minute or a reported error.

attributes.collector_version
string or null

The collector version running on the host, or null before its first ping.

attributes.pinged_at
string or null

When the host last pinged Better Stack, as an ISO 8601 date-time in UTC, or null before its first ping.

attributes.first_pinged_at
string or null

When the host first pinged Better Stack, as an ISO 8601 date-time in UTC, or null before its first ping.

attributes.last_error
string or null

The error the host reported on its last ping, an empty string when there was none, or null before its first ping.

attributes.installed_as
string

The platform the host reported, docker, swarm or kubernetes, or an empty string before it reports one.

attributes.system_information
object

Kernel and eBPF compatibility details the host reported, such as kernel_version, architecture, distribution and ebpf_supported, or an empty object before it reports them.

Example Request

cURL
curl -L -H "Authorization: Bearer $TOKEN" \
     "https://telemetry.betterstack.com/api/v1/collectors/1/hosts"


Previous article

Remove a collector

Next article

Lists databases monitored by a collector