Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. Vector
    3. OpenTelemetry
    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. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources API
    3. Source groups API
    4. Metrics API
    5. Dashboards API
    6. Connections API
    7. 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
    8. Query API ↗
  7. Alternative to
    1. Lightstep

Update a collector

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

The platform, data_region, and custom_bucket attributes are immutable and cannot be changed after a collector is created.

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

URL parameters

id
required string

The unique identifier of the collector to update.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

name
string

A new unique name for the collector.

note
string

A new note for the collector. Send null to clear the existing note.

logs_retention
integer

Custom retention period for logs, in days. This is only available on select plans.

metrics_retention
integer

Custom retention period for metrics, in days. This is only available on select plans.

ingesting_paused
boolean

Set to true to pause data ingestion, or false to resume.

source_vrl_transformation
string

A VRL program to be applied to logs server-side. Send null to remove.

user_vector_config
string

A custom Vector configuration in YAML format. Send null to remove.

configuration
object

An object containing detailed configuration options to update. Only the keys provided in this object will be modified.

proxy_config
object

An object containing proxy-specific settings to update. To clear the HTTP basic auth password, send http_basic_auth_password: null.

databases
array

An array of database objects to add, update, or remove. To remove a database, include its id and set _destroy: true.

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

The collector was updated successfully.

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": 123,
      "team_name": "My Team",
      "data_region": "a3",
      "logs_retention": 60,
      "metrics_retention": 180,
      "configuration": {
        "components": {
          "logs_docker": true
        },
        "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"
      },
      "proxy_config": null,
      "user_vector_config": null,
      "ingesting_paused": false,
      "source_vrl_transformation": null,
      "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
    }
  }
}
404

A collector with the specified ID was not found.

422

Validation failed due to invalid or unsupported parameters.

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/v1/collectors/1" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "note": "Updated note for production collector.",
       "configuration": {
         "logs_sample_rate": 50
       }
     }'


Previous article

Create a collector

Next article

Remove a collector