Send your first metric

Metrics are sent with POST /v1/metrics/{metricName}. Each request contains one or more entries for the same metric name.

Use a single numeric value when you have one observation at one timestamp. Use a statisticSet when your application has already aggregated multiple observations into min, max, avg, and sampleCount.

Before you send data

You need a workspace-scoped API token with Write access to the metric resource. Send it as a bearer token:

Authorization: Bearer $METRICS_TOKEN
Content-Type: application/json

Timestamps are Unix epoch milliseconds. If resolution is omitted, the API stores the point at one-second resolution.

See Metric rollups and resolution before choosing a resolution for production metrics.

Option 1: Single value

Send a value when one entry represents one sample.

curl -X POST "$METRICS_API_URL/v1/metrics/cpu_usage" \
-H "Authorization: Bearer $METRICS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "entries": [
    {
      "timestamp": 1779433200000,
      "value": 42.7,
      "resolution": 60,
      "dimensions": [
        { "name": "host", "value": "api-1" },
        { "name": "region", "value": "us-west" }
      ]
    }
  ]
}'

The API stores this as a sample count of 1. Querying the metric with aggregation=count returns 1 for that bucket.

Option 2: Min, max, avg, count

Send a statisticSet when one entry represents several samples that were already summarized by your code.

curl -X POST "$METRICS_API_URL/v1/metrics/request_latency" \
-H "Authorization: Bearer $METRICS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "entries": [
    {
      "timestamp": 1779433200000,
      "resolution": 60,
      "statisticSet": {
        "min": 12.4,
        "max": 88.9,
        "avg": 31.6,
        "sampleCount": 25
      },
      "dimensions": [
        { "name": "route", "value": "GET /v1/metrics" },
        { "name": "status", "value": "200" }
      ]
    }
  ]
}'

sampleCount is the count for the statistic set. Querying with aggregation=count returns the sum of sampleCount values in each returned bucket.

Choosing between them

Use value for direct measurements such as a gauge, a queue depth, or a single request duration.

Use statisticSet when you flush buffered measurements from a client, agent, or job. It reduces payload size without losing the data needed for min, max, avg, sum, and count queries.

Distribution aggregations are the exception. A statistic set carries only min, max, avg, and sampleCount, so the distribution within the set is not preserved. percentile(95) and trimmed_mean(10;10) queries are accurate for individual value entries, but approximate toward the average for statistic sets. Send individual value entries when you need accurate percentiles or trimmed means.