Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. OpenTelemetry
    3. Vector
    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. Grafana
    7. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources & collectors
      1. Sources API
      2. 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. List collector metrics targets GET
        9. Get a single collector metrics target GET
        10. Create a collector metric target POST
        11. Update a collector metrics target PATCH
        12. Remove a collector metric target DELETE
      3. Metrics API
      4. Source groups API
    3. Dashboards
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
  7. Alternative to
    1. Lightstep

Create a collector metric target

Creates a new monitoring target on a collector.

Each target kind accepts a specific set of connection fields. Sending a field that does not apply to the chosen kind (for example, ssl_mode on a redis target) will return a validation error.

POST https://telemetry.betterstack.com/api/v1/collectors/{collector_id}/targets

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

kind
required string

The type of target. Valid options are postgres, mysql, redis, mongodb, memcached, elasticsearch, nginx, apache, kafka, and prometheus.

host
required string

The hostname or IP address of the target.

port
integer

The port number. Required for database kinds, optional for process kinds.

service
string

The service or container name. Required for process kinds (nginx, apache, kafka, prometheus).

listen_ip
string

The IP address the process listens on. Only accepted for nginx, apache, and kafka.

endpoint
string

The full scrape URL (e.g. http://10.0.0.5:9090/metrics). Required for prometheus targets.

username
string

The username for authentication. Only accepted for database kinds and elasticsearch.

password
string

The password for authentication. Only accepted for database kinds and elasticsearch. Write-only — never returned in responses.

api_key
string

An API key for authentication. Only accepted for elasticsearch. Write-only — never returned in responses.

ssl_mode
string

The SSL mode for the connection. Required for postgres. Valid options are disable, require, and verify-ca.

tls
string

The TLS mode for the connection. Required for mysql. Valid options are false, true, skip-verify, and preferred.

scheme
string

The connection scheme. Only accepted for elasticsearch. Valid options are http and https. Defaults to http if omitted.

enabled
boolean

Set to false to create the target in a disabled state. Defaults to true.

Fields accepted per kind

Kind Required fields Optional fields
postgres host, port, ssl_mode username, password
mysql host, port, tls username, password
redis host, port username, password
mongodb host, port username, password
memcached host, port username, password
elasticsearch host, port username, password, api_key, scheme
nginx host, service port, listen_ip
apache host, service port, listen_ip
kafka host, service port, listen_ip
prometheus host, service, endpoint —
201

The target was created successfully.

Response body

{
  "data": {
    "id": "10",
    "type": "collector_target",
    "attributes": {
      "kind": "postgres",
      "host": "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": null,
      "created_at": "2025-06-15T12:00:00.000Z",
      "updated_at": "2025-06-15T12:00:00.000Z"
    }
  }
}
422

Validation failed due to invalid parameters.

Response body

{
  "errors": [
    "Ssl mode can't be blank"
  ],
  "invalid_attributes": [
    "ssl_mode"
  ]
}

Example: PostgreSQL target

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "postgres",
       "host": "db.example.com",
       "port": 5432,
       "username": "monitor",
       "password": "secret",
       "ssl_mode": "require"
     }'


Example: Elasticsearch target with API key

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "elasticsearch",
       "host": "es.example.com",
       "port": 9200,
       "scheme": "https",
       "api_key": "VnVhQ19fb29CT0hraHQyVEhhV0M6..."
     }'


Example: Nginx process target

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "nginx",
       "host": "collector-host-1",
       "service": "edge-nginx",
       "listen_ip": "10.0.0.1",
       "port": 80
     }'


Example: Prometheus target

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "prometheus",
       "host": "collector-host-1",
       "service": "my-app",
       "endpoint": "http://10.0.0.5:9090/metrics"
     }'


Example: Create disabled

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "redis",
       "host": "r.example.com",
       "port": 6379,
       "enabled": false
     }'


Previous article

Get a single collector metrics target

Next article

Update a collector metrics target