# Update a collector

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

[warning]
The `platform`, `data_region`, and `custom_bucket` attributes are immutable and cannot be changed after a collector is created.
[/warning]

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v1/collectors/{id}"
method = "PATCH"

[[path_param]]
name = "id"
description = "The unique identifier of the collector to update."
required = true
type = "string"

[[body_param]]
name = "name"
description = "A new unique name for the collector."
required = false
type = "string"

[[body_param]]
name = "note"
description = "A new note for the collector. Send `null` to clear the existing note."
required = false
type = "string"

[[body_param]]
name = "logs_retention"
description = "Custom retention period for logs, in days. This is only available on select plans."
required = false
type = "integer"

[[body_param]]
name = "metrics_retention"
description = "Custom retention period for metrics, in days. This is only available on select plans."
required = false
type = "integer"

[[body_param]]
name = "ingesting_paused"
description = "Set to `true` to pause data ingestion, or `false` to resume."
required = false
type = "boolean"

[[body_param]]
name = "source_group_id"
description = "The ID of the resource group to assign the collector's associated sources to. Send `0` or `null` to remove the assignment."
required = false
type = "integer"

[[body_param]]
name = "live_tail_pattern"
description = """
A custom format for messages displayed in live tail, with columns wrapped in `{column}` brackets. Example: `"PID: {message_json.pid} {level} {message}"`. Send `null` to clear.  \nFor details, see [Live tail docs](https://betterstack.com/docs/logs/using-logtail/formatting-logs/#live-tail-message-format).
"""
required = false
type = "string"

[[body_param]]
name = "source_vrl_transformation"
description = "A [VRL program](https://betterstack.com/docs/logs/using-logtail/transforming-ingested-data/logs-vrl/) to be applied to logs server-side. Send `null` to remove."
required = false
type = "string"

[[body_param]]
name = "user_vector_config"
description = "A custom Vector configuration in YAML format. Send `null` to remove."
required = false
type = "string"

[[body_param]]
name = "configuration"
description = "An object containing detailed configuration options to update. Only the keys provided in this object will be modified. For a full list of options, see the `configuration` object section in the [Create collector API documentation](https://betterstack.com/docs/logs/api/create-a-collector/)."
required = false
type = "object"

[[body_param]]
name = "databases"
description = "An array of database objects to add, update, or remove. To remove a database, include its `id` and set `_destroy: true`."
required = false
type = "array"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

### 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`.

```json
[label 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 }
  ]
}
```

[responses]
[[response]]
status = 200
description = "The collector was updated successfully."
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,
          "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"
      },
      "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
    }
  }
}
'''

[[response]]
status = 404
description = "A collector with the specified ID was not found."

[[response]]
status = 422
description = "Validation failed due to invalid or unsupported parameters."
body = '''
{
  "errors": ["Data region can't be changed. Create a new collector to change your data region."],
  "invalid_attributes": ["data_region"]
}
'''
[/responses]

#### Example Request

```shell
[label 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": {
         "components": {
           "ebpf_metrics": false
         },
         "logs_sample_rate": 50
       }
     }'
```