Update a collector

Updates an existing collector. Only the provided parameters will be changed.

The platform and data_region attributes are immutable and cannot be changed after a collector is created. A custom bucket can only be added when creating a collector.

PATCH https://telemetry.betterstack.com/api/v2/collectors/{id}

URL parameters

id
required string

Headers

Authorization
required string

Body parameters

name
string
note
string
logs_retention
integer
metrics_retention
integer
ingesting_paused
boolean
source_group_id
integer
live_tail_pattern
string
source_vrl_transformation
string
user_vector_config
string
configuration
object
databases
array of objects
custom_bucket
object
connected_source_ids
array of integers
service_fields
array of objects
service_fields[].name_key
required string
service_fields[].type_key
string or null

Updating Databases

To manage monitored databases, provide an array to the databases parameter. Each object in the array can either update an existing database (by providing its id) or create a new one (by omitting the id). To delete a database, include its id and set _destroy: true.

Example `databases` payload
{
  "databases": [
    { "id": 1, "host": "updated-db.example.com" },
    { "service_type": "redis", "host": "new-redis.example.com", "port": 6379 },
    { "id": 2, "_destroy": true }
  ]
}
200

Response body

{
  "data": {
    "id": "1",
    "type": "collector",
    "attributes": {
      "name": "Renamed Collector",
      "platform": "docker",
      "note": "This note has been updated.",
      "status": "online",
      "secret": "collector-secret-goes-here",
      "team_id": "t123",
      "team_name": "My Team",
      "data_region": "a3",
      "logs_retention": 60,
      "metrics_retention": 180,
      "configuration": {
        "components": {
          "logs_docker": true,
          "ebpf_metrics": false
        },
        "logs_sample_rate": 50,
        "traces_sample_rate": 100,
        "vrl_transformation": null,
        "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_id": 12345,
      "source_group_id": 678,
      "live_tail_pattern": "Updated pattern: {level}",
      "pinged_at": "2023-10-27T10:00:00.000Z",
      "created_at": "2023-10-26T10:00:00.000Z",
      "updated_at": "2023-10-28T14:00:00.000Z",
      "custom_bucket": null,
      "connected_source_ids": [
        12346
      ],
      "service_fields": [
        {
          "name_key": "service.name",
          "type_key": "service.type"
        }
      ]
    }
  }
}
404
422

Response body

{
  "errors": [
    "Data region can't be changed. Create a new collector to change your data region."
  ],
  "invalid_attributes": [
    "data_region"
  ]
}

Example Request

cURL
curl -X PATCH "https://telemetry.betterstack.com/api/v2/collectors/1" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "note": "Updated note for production collector.",
       "configuration": {
         "components": {
           "ebpf_metrics": false
         },
         "logs_sample_rate": 50
       }
     }'