# Send your first metric

Publish raw values or pre-aggregated statistic sets to the Metrics API.

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:

```bash
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](/docs/metric-rollups-resolution) before choosing a resolution for production metrics.

## Option 1: Single value

Send a `value` when one entry represents one sample.

```bash
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.

```bash
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.