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
        1. List all sources GET
        2. Get a single source GET
        3. Create a source POST
        4. Update a source PATCH
        5. Remove a source DELETE
        6. Connect to AWS PATCH
        7. Connect to GCP PATCH
        8. Log group subscriptions GET
      2. Collectors API
      3. Collector metrics targets API
      4. Metrics API
      5. Source groups API
    3. Dashboards
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
    8. Usage API ↗
  7. Alternative to
    1. Lightstep

Update a source

Updates an existing source. Send only the parameters you wish to change (e.g. name )

PATCH https://telemetry.betterstack.com/api/v2/sources/{source_id}

URL parameters

id
required string

ID of the source you want to update

Body parameters

name
string

Source name

ingesting_paused
boolean

Enable or disable ingesting for this source

source_group_id
integer

The ID of the source group this source belongs to

live_tail_pattern
string

Live tail message format with columns wrapped in {column} brackets.
Example: "PID: {message_json.pid} {level} {message}".
For details, see Live tail docs.

logs_retention
integer

Data retention for logs in days. There might be additional charges for longer retention.

metrics_retention
integer

Data retention for metrics in days. There might be additional charges for longer retention.

vrl_transformation_logs
string

The VRL code applied to logs during ingestion. Send an empty string to remove the transformation, or null to reset it to the platform default. Read more about VRL transformations.

vrl_transformation_spans
string

The VRL code applied to traces (spans) during ingestion. Send an empty string to remove the transformation. Read more about VRL transformations.

blocked_metrics
array

Metric names to mark as spam. Listed metrics are rejected during ingestion and aren't billed.

scrape_urls
array

URLs to scrape by prometheus_scrape platform and similar.

scrape_frequency_secs
integer

How often to scrape the URLs for prometheus_scrape platform and similar. Permitted values are 15, 30, 60, 120 or 300.

scrape_request_headers
array

An array of request headers for prometheus_scrape platform and similar, with each object containing name and value fields.

scrape_request_basic_auth_user
string

Basic auth username for prometheus_scrape platform and similar.

scrape_request_basic_auth_password
string

Basic auth password for prometheus_scrape platform and similar.

skip_ssl_verify
boolean

Whether to skip SSL/TLS certificate verification for prometheus_scrape platform and similar. Set to true to disable verification.

aws_auto_sub_log_groups
boolean

Only for aws sources. Whether Better Stack automatically subscribes newly discovered Amazon CloudWatch log groups for ingestion. Defaults to true. Set to false to subscribe log groups yourself.

custom_bucket
object

Rotates the key pair of the custom bucket the source already uses. Send only access_key_id and secret_access_key. We verify the new pair against the bucket first; if that fails, the whole request is rejected with a 422 and nothing is changed. A bucket shared by several sources is rotated for all of them. Send the new pair before deactivating the old one to rotate without downtime. A custom bucket can only be added when creating a source.

200

The source was updated

Response body

{
  "id": "95",
  "type": "source",
  "attributes": {
    "source_group_id": 572,
    "team_id": 123,
    "team_name": "Test team",
    "name": "Nginx",
    "platform": "nginx",
    "table_name": "nginx",
    "token": "FczKcxEhjEDE58dBX7XaeX1q",
    "ingesting_paused": false,
    "ingesting_host": "s95.eu-nbg-2.betterstackdata.com",
    "created_at": "2026-05-27T12:30:41.695Z",
    "updated_at": "2026-06-11T14:00:50.756Z",
    "logs_retention": 7,
    "metrics_retention": 14,
    "live_tail_pattern": "{level} {host} {nginx.status} {nginx.method} {nginx.host} {nginx.path} {nginx.client} {nginx.agent} {message}",
    "data_region": "eu-nbg-2",
    "custom_bucket": {
      "name": "storage-bucket",
      "endpoint": "https://s3.us-east-1.amazonaws.com/storage-bucket",
      "access_key_id": "AKIAIOSFODNN7EXAMPLE"
    },
    "vrl_transformation_logs": ".message = upcase!(.message)\n.",
    "vrl_transformation_spans": ".name = downcase!(.name)\n.",
    "blocked_metrics": [
      "go_gc_duration_seconds",
      "go_memstats_heap_idle_bytes"
    ]
  }
}
404

Your team has no source with the given ID

Response body

{
  "errors": "Resource with provided ID was not found"
}
422

Validation failed

Response body

{
  "errors": "Your plan doesn't support custom retention",
  "invalid_attributes": [
    "logs_retention",
    "metrics_retention"
  ]
}

Example cURL

Example
curl --request PATCH \
  --url https://telemetry.betterstack.com/api/v2/sources/123 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "My renamed HTTP source"
  }'


Previous article

Create a source

Next article

Remove a source