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.