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 numeric value for one observation, a statisticSet for summary statistics, or a histogram for a bucketed distribution. Each entry must contain exactly one of these fields.

Metric and dimension names accept letters, numbers, dots, underscores, and hyphens. For example, publish http.requests with a service.name dimension; use the same dimension name when filtering or listing its values.

Numeric limits

value, histogram bounds, min, and max, and statistic-set min, max, and avg accept numbers from -9007199254740992 to 9007199254740992 (inclusive, ±2^53), with at most 10 decimal places, ignoring trailing zeros. Histogram sum accepts numbers from -19342813104826867540557824 to 19342813104826867540557824, with the same decimal limit. Values outside these limits are rejected.

Measurements use double-precision floating-point storage. Every integer in this range is exactly representable; fractional values and aggregation results can be rounded. Accepting 10 decimal places does not guarantee that all those digits are preserved.

sampleCount and the sum of a histogram's bucket counts are limited to 1 through 2147483647, inclusive.

Metric descriptions and explicit creation

Use PUT /v1/metrics/{metricName}/metadata with {"description": "Request duration in milliseconds"} to create a metric before sending data, or update an existing metric's description. This requires metric write permission. Descriptions are plain text, support spaces and line breaks, and have a maximum of 1,024 characters. Send {"description": ""} or {} to reset the description to its default empty string. Descriptions are returned by the metrics list and displayed beneath the metric name.

Explicit creation adds no dimension combinations and incurs no metric-combination charges. The first data write creates and bills combinations under the usual rules. Explicitly created metrics remain until deleted, even after their data expires or their description is cleared; expired combinations still stop billing. Updating the description of a metric originally created by ingestion does not change its cleanup behavior. Sending data continues to create missing metrics automatically.

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.

Partial statistic sets require sampleCount and at least one of avg, min, or max. Missing avg is estimated as the midpoint of min and max, or the sole supplied extremum. Missing min and max use avg. Midpoints are rounded to 10 decimal places using half-even rounding. The completed set must satisfy min <= avg <= max.

For example, {"min": 2, "max": 18, "sampleCount": 4} is stored with avg: 10; {"avg": 10, "sampleCount": 4} is stored with min: 10 and max: 10. Queries use these completed values, so omitted statistics are estimates rather than recovered measurements. Older Java SDK releases may require all three statistics; use an updated SDK or send the partial set over HTTP.

Option 3: Histogram

Send a histogram when your application has already counted observations into ranges and you want to preserve more of their distribution.

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,
        "histogram": {
          "bounds": [10, 25, 50],
          "bucketCounts": [0, 7, 2, 0]
        },
        "dimensions": [
          { "name": "route", "value": "GET /v1/metrics" }
        ]
      }
    ]
  }'

bounds are strictly increasing inclusive upper bounds. bucketCounts are non-cumulative and must contain exactly one more item than bounds: the first count covers values through the first bound, and the last covers values above the final bound.

An empty bounds array is allowed with exactly one bucket count when both min and max are supplied.

You may supply sum, min, and max. When they are omitted, the API estimates them from the populated buckets after clipping their edges to any supplied min and max. Finite buckets use a uniform distribution and their midpoint for the sum. For an unbounded first bucket, a positive upper edge uses zero as its lower edge; a non-positive upper edge is used for both edges. An unbounded final bucket uses its lower edge for both edges. Supplied summaries must be consistent with the populated buckets.

Histogram percentile and trimmed-mean results are estimates because the exact observations within each submitted bucket are unknown. Narrower buckets preserve more distribution detail.

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.

Use histogram when percentile and trimmed-mean queries matter and your source already aggregates observations into buckets. Histograms retain the bucket populations, while statistic sets retain only summary values. Send individual value entries for the highest available distribution accuracy.