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
      3. Collector metrics targets API
      4. Metrics API
        1. List all metrics GET
        2. Create a metric POST
        3. Update a metric PATCH
        4. Remove a metric DELETE
      5. Source groups API
    3. Dashboards
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
  7. Alternative to
    1. Lightstep

Create a metric

Returns a newly created metric or label.

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

URL parameters

source_id
required integer

Source for which to create a metric

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

team_name
string

Required if using global API token to specify the team which should own the resource

name
required string

Metric name

sql_expression
required string

SQL expression to use for the metric

aggregations
array

Aggregations to apply to the metric. Keep empty to create a label instead.
Valid aggregations are avg, count, uniq, max, min, sum, and histogram.

201

Response body

{
  "data": {
    "id": "g-123",
    "type": "metric",
    "attributes": {
      "name": "level",
      "sql_expression": "JSONExtract(raw, 'level', 'Nullable(String)')",
      "aggregations": [],
      "type": "string_low_cardinality"
    }
  }
}

Example cURL

Create a metric Create a label 
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/sources/123/metrics \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "duration_ms",
    "sql_expression": "JSONExtract(raw, '\''message_json'\'', '\''duration_ms'\'', '\''Nullable(Float64)'\'')",
    "aggregations": ["avg", "histogram", "min", "max"]
  }'
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/sources/123/metrics \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "log_type",
    "sql_expression": "JSONExtractString(raw, '\''message_json'\'', '\''log_type'\'')"
  }'


Previous article

List all metrics

Next article

Update a metric