# Update a collector metrics target

Updates an existing collector target. Only include the fields you want to change — omitted fields are preserved.

[info]
The `kind` field cannot be changed after creation. To switch to a different kind, remove the target and create a new one.
[/info]

[info]
Changing any connection field (`host`, `port`, `username`, `password`, `ssl_mode`, `tls`, `scheme`, `listen_ip`, `endpoint`, `api_key`) resets the target's status to `pending` so the collector can re-verify the connection.
[/info]

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

[[url_param]]
name = "collector_id"
description = "The ID of the collector."
required = true
type = "string"

[[url_param]]
name = "target_id"
description = "The ID of the target."
required = true
type = "string"

[[body_param]]
name = "host"
description = "The hostname or IP address of the target."
required = false
type = "string"

[[body_param]]
name = "port"
description = "The port number."
required = false
type = "integer"

[[body_param]]
name = "service"
description = "The service or container name (process kinds only)."
required = false
type = "string"

[[body_param]]
name = "listen_ip"
description = "The IP address the process listens on (`nginx`, `apache`, `kafka` only)."
required = false
type = "string"

[[body_param]]
name = "endpoint"
description = "The full scrape URL (`prometheus` only)."
required = false
type = "string"

[[body_param]]
name = "username"
description = "The username for authentication."
required = false
type = "string"

[[body_param]]
name = "password"
description = "The password for authentication. Write-only — never returned in responses."
required = false
type = "string"

[[body_param]]
name = "api_key"
description = "An API key for authentication (`elasticsearch` only). Write-only — never returned in responses."
required = false
type = "string"

[[body_param]]
name = "ssl_mode"
description = "The SSL mode for the connection (`postgres` only). Valid options are `disable`, `require`, and `verify-ca`."
required = false
type = "string"

[[body_param]]
name = "tls"
description = "The TLS mode for the connection (`mysql` only). Valid options are `false`, `true`, `skip-verify`, and `preferred`."
required = false
type = "string"

[[body_param]]
name = "scheme"
description = "The connection scheme (`elasticsearch` only). Valid options are `http` and `https`."
required = false
type = "string"

[[body_param]]
name = "enabled"
description = "Set to `false` to disable the target, or `true` to re-enable it."
required = false
type = "boolean"

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

[responses]
[[response]]
status = 200
description = "The target was updated successfully."
body = '''
{
  "data": {
    "id": "1",
    "type": "collector_target",
    "attributes": {
      "kind": "postgres",
      "host": "new-db.example.com",
      "port": 5432,
      "service": null,
      "listen_ip": null,
      "endpoint": null,
      "scheme": null,
      "username": "monitor",
      "ssl_mode": "require",
      "tls": null,
      "status": "pending",
      "enabled": true,
      "container": null,
      "detected_host": null,
      "autogenerated": false,
      "paused_until": null,
      "consecutive_failure_count": 0,
      "last_ping_at": "2025-06-15T14:32:00.000Z",
      "created_at": "2025-06-01T12:00:00.000Z",
      "updated_at": "2025-06-16T09:00:00.000Z"
    }
  }
}
'''
[[response]]
status = 422
description = "Validation failed due to invalid parameters."
body = '''
{
  "errors": [
    "Ssl mode can't be blank"
  ],
  "invalid_attributes": [
    "ssl_mode"
  ]
}
'''
[[response]]
status = 404
description = "The target was not found, or belongs to a different collector or team."
body = '''
{
  "errors": "Not found"
}
'''
[/responses]

#### Example: Change host

```shell
[label cURL]
curl -X PATCH "https://telemetry.betterstack.com/api/v1/collectors/1/targets/1" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "host": "new-db.example.com"
     }'
```

#### Example: Rotate credentials

```shell
[label cURL]
curl -X PATCH "https://telemetry.betterstack.com/api/v1/collectors/1/targets/1" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "new-monitor",
       "password": "new-secret"
     }'
```

#### Example: Disable a target

```shell
[label cURL]
curl -X PATCH "https://telemetry.betterstack.com/api/v1/collectors/1/targets/1" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "enabled": false
     }'
```