List all collectors

GET https://telemetry.betterstack.com/api/v1/collectors

Query parameters

page

1 integer

Page number for pagination.

per_page

50 integer

Number of items per page (max 250).

name

string

Filter collectors by name (case-insensitive partial match).

team_name

string

Required if using a global API token to filter for a specific team. If omitted, collectors from all teams in the organization are returned.

Headers

Authorization

required string

Bearer $TOKEN

200

Returns a paginated list of collectors.

Response body

{
  "data": [
    {
      "id": "1",
      "type": "collector",
      "attributes": {
        "name": "Production Kubernetes",
        "platform": "kubernetes",
        "note": "Main cluster for production services.",
        "status": "up",
        "secret": "collector-secret-goes-here",
        "team_id": 123,
        "team_name": "My Team",
        "data_region": "a3",
        "logs_retention": 30,
        "metrics_retention": 90,
        "configuration": {
          "components": {
            "logs_host": true,
            "logs_docker": true,
            "logs_kubernetes": true,
            "logs_collector_internals": true,
            "metrics_cluster": true,
            "metrics_databases": true,
            "metrics_other_databases": true,
            "metrics_host_os": true,
            "metrics_postgres": true,
            "metrics_mysql": true,
            "metrics_elasticsearch": true,
            "metrics_pgbouncer": true,
            "metrics_nginx": true,
            "metrics_apache": true,
            "metrics_traefik": true,
            "ebpf_metrics": true,
            "ebpf_tracing_basic": false,
            "ebpf_tracing_full": true,
            "ebpf_java_agent": false,
            "traces_opentelemetry": false,
            "ebpf_red_metrics": true
          },
          "logs_sample_rate": 100,
          "traces_sample_rate": 100,
          "vrl_transformation": "\n.",
          "merge_logs": false,
          "disk_batch_size_mb": 256,
          "memory_batch_size_mb": 10,
          "when_full": "drop_newest",
          "log_line_length_limit_kb": 8
        },
        "user_vector_config": null,
        "ingesting_paused": false,
        "source_vrl_transformation": null,
        "source_group_id": null,
        "live_tail_pattern": null,
        "source_id": 9876,
        "pinged_at": "2023-10-27T10:00:00.000Z",
        "created_at": "2023-10-26T10:00:00.000Z",
        "updated_at": "2023-10-26T10:00:00.000Z",
        "custom_bucket": null
      }
    }
  ],
  "pagination": {
    "first": "https://telemetry.betterstack.com/api/v1/collectors?page=1&per_page=1",
    "last": "https://telemetry.betterstack.com/api/v1/collectors?page=2&per_page=1",
    "prev": null,
    "next": "https://telemetry.betterstack.com/api/v1/collectors?page=2&per_page=1"
  }
}

401

Invalid or missing authentication token.

Response attributes

string

The ID of the collector.

type

string

Always collector.

attributes.name

string

The name of the collector.

attributes.platform

string

The platform the collector runs on: docker, swarm or kubernetes.

attributes.note

string or null

A free-form note about the collector, or null when there is none.

attributes.status

string

The collector's status, computed from its hosts: pending, up, degraded, unknown, partially_up, unsupported_version or down.

attributes.secret

string

The secret the collector uses to connect to Better Stack.

attributes.team_id

integer

The ID of the team the collector belongs to.

attributes.team_name

string

The name of the team the collector belongs to.

attributes.data_region

string

The internal name of the storage region that holds the collector's data, such as a3, which differs from the region ID accepted on create.

attributes.logs_retention

integer

How many days logs are retained.

attributes.metrics_retention

integer

How many days metrics are retained.

attributes.configuration

object

The collector's configuration, or an empty object when it has none yet.

attributes.configuration.components

object

Boolean flags for each data collection component, listed below.

attributes.configuration.components.logs_host

boolean

Whether the collector collects logs from the host's /var/log directory.

attributes.configuration.components.logs_docker

boolean

Whether the collector collects logs of Docker containers that use the default json-file logging driver.

attributes.configuration.components.logs_kubernetes

boolean

Whether the collector collects Kubernetes container logs and events.

attributes.configuration.components.logs_collector_internals

boolean

Whether the collector sends its own internal logs.

attributes.configuration.components.metrics_cluster

boolean

Whether the collector collects Kubernetes object state metrics for pods, workloads, nodes and volumes.

attributes.configuration.components.metrics_databases

boolean

Legacy alias of metrics_cluster, always the same value.

attributes.configuration.components.metrics_other_databases

boolean

Whether the collector collects Redis, MongoDB, Memcached and Kafka metrics, plus supplementary PostgreSQL, MySQL and connection pooler metrics.

attributes.configuration.components.metrics_host_os

boolean

Whether the collector collects CPU, memory, disk, filesystem and network metrics of the host with node_exporter.

attributes.configuration.components.metrics_postgres

boolean

Whether the collector collects PostgreSQL metrics.

attributes.configuration.components.metrics_mysql

boolean

Whether the collector collects MySQL metrics.

attributes.configuration.components.metrics_elasticsearch

boolean

Whether the collector collects Elasticsearch metrics.

attributes.configuration.components.metrics_pgbouncer

boolean

Whether the collector collects PgBouncer metrics.

attributes.configuration.components.metrics_nginx

boolean

Whether the collector collects Nginx metrics.

attributes.configuration.components.metrics_apache

boolean

Whether the collector collects Apache metrics.

attributes.configuration.components.metrics_traefik

boolean

Whether the collector collects Traefik metrics.

attributes.configuration.components.ebpf_metrics

boolean

Whether the collector collects host metrics with eBPF.

attributes.configuration.components.ebpf_tracing_basic

boolean

Whether basic eBPF distributed tracing is on, which propagates context through headers only and may produce incomplete traces.

attributes.configuration.components.ebpf_tracing_full

boolean

Whether full eBPF distributed tracing is on, which propagates context through headers and TCP.

attributes.configuration.components.ebpf_java_agent

boolean

Whether the Java agent is injected into JVMs for visibility into TLS connections, such as HTTPS and MySQL, in eBPF traces.

attributes.configuration.components.traces_opentelemetry

boolean

Whether the collector accepts OpenTelemetry SDK traces on port 4317 over OTLP/gRPC and port 4318 over OTLP/HTTP.

attributes.configuration.components.ebpf_red_metrics

boolean

Whether the collector builds the service map and RED metrics, meaning requests, error rate and duration, with eBPF.

attributes.configuration.logs_sample_rate

integer

The percentage of logs the collector sends, from 0 to 100.

attributes.configuration.traces_sample_rate

integer

The percentage of traces the collector sends, from 0 to 100.

attributes.configuration.vrl_transformation

string

The VRL program the collector runs on logs before sending them.

attributes.configuration.merge_logs

boolean

Whether the collector merges multi-line logs into single logs.

attributes.configuration.merge_logs_config

string

The VRL condition that marks the first line of a new log when merging, omitted when not set.

attributes.configuration.disk_batch_size_mb

integer

The maximum size of the on-disk buffer in MB, omitted when not set and the default of 3000 applies.

attributes.configuration.memory_batch_size_mb

integer

The maximum size of each batch the collector sends in MB, omitted when not set and the default of 20 applies.

attributes.configuration.buffer_max_events

integer

How many events the in-memory buffer holds before it overflows to disk, omitted when not set and the default of 10000 applies.

attributes.configuration.when_full

string

What the collector does when the disk buffer is full: drop_newest drops new data and block waits, omitted when not set.

attributes.configuration.log_line_length_limit_kb

integer

The log line length in kB above which logs are dropped, omitted when not set and the default of 8 applies.

attributes.configuration.namespaces_options

object

Per-namespace overrides for log sampling and trace ingestion, keyed by Kubernetes namespace, omitted when there are none.

attributes.configuration.services_options

object

Per-service overrides for log sampling and trace ingestion, keyed by service name, omitted when there are none.

attributes.user_vector_config

string or null

Your custom Vector configuration in YAML, or null when it is the default.

attributes.ingesting_paused

boolean

Whether ingestion for the collector's source is paused.

attributes.source_vrl_transformation

string or null

The VRL program Better Stack runs on the collector's logs during ingestion, or null when there is none.

attributes.source_group_id

integer or null

The ID of the source group the collector's source is in, or null when it isn't in a group.

attributes.live_tail_pattern

string or null

The format of lines in Live tail, such as {level} {message}, or null when the source serves only metrics.

attributes.source_id

integer

The ID of the source that receives the collector's data.

attributes.pinged_at

string or null

When a host of the collector last pinged Better Stack, as an ISO 8601 date-time in UTC, or null when no host has pinged yet.

attributes.created_at

string

When the collector was created, as an ISO 8601 date-time in UTC.

attributes.updated_at

string

When the collector was last updated, as an ISO 8601 date-time in UTC.

attributes.custom_bucket

object or null

Your own S3-compatible bucket that stores the collector's data, or null when it uses Better Stack storage.

attributes.custom_bucket.name

string

The name of the bucket.

attributes.custom_bucket.endpoint

string

The endpoint URL of the bucket.

attributes.custom_bucket.access_key_id

string

The access key ID for the bucket.

attributes.custom_bucket.keep_data_after_retention

boolean

Whether data stays in the bucket after the retention period ends.

pagination.first

string

URL of the first page. Read more about pagination.

pagination.last

string

URL of the last page.

pagination.prev

string or null

URL of the previous page, or null on the first page.

pagination.next

string or null

URL of the next page, or null on the last page.

Explore documentation

Example Request

Explore documentation

List all collectors

Example Request

Please accept cookies