# Publish custom metrics

Send your own numbers to a custom metric series over the API or the CLI, and see which datums were refused.

A **series** is a namespace, a metric name and up to ten dimensions (`route=/pay`, `region=eu`):
the same name with other dimensions is another series. A series exists from its first datum on.
Values are aggregated per minute on arrival, so average, sum, minimum, maximum and sample count
stay exact whatever you send. OpenTelemetry and StatsD land in the same series; see
[Send OpenTelemetry metrics](send-opentelemetry-metrics.md) and
[Send StatsD metrics from an app](send-statsd-metrics.md).

The points you keep are metered storage (see [What is Monitoring?](what-is.md)).

## Prerequisites

- Permission for `monitoring:PutMetricData` on `rn:ews::<organization id>:monitoring:*`.
- Room in the **Custom metric series** quota for a new series (see [Quotas](quotas.md)).

## Publish datapoints

**Console:** not available. The console charts custom metrics but does not publish them.
**CLI**
The CLI takes one `--metric-data` per datum:

```sh
dcloud monitoring custom-metrics put --namespace Shop \
  --metric-data '{"metricName":"orders_placed","value":1,"dimensions":{"region":"eu"}}' \
  --metric-data '{"metricName":"checkout_ms","values":[120,95,310],"unit":"Milliseconds"}'
```

**API**
```http
POST /monitoring/api/custom-metrics
{
  "namespace": "Shop",
  "metricData": [
    { "metricName": "orders_placed", "value": 1, "dimensions": { "region": "eu" } },
    { "metricName": "checkout_ms", "values": [120, 95, 310], "unit": "Milliseconds" },
    { "metricName": "batch_size", "timestamp": "2026-11-10T12:00:00Z",
      "statistics": { "count": 40, "sum": 812, "min": 3, "max": 61 } }
  ]
}
```

Each datum has exactly one of `value`, `values` (up to 150, with an optional `counts` of the same
length saying how often each occurred) or `statistics` (a pre-aggregated `count`, `sum`, `min` and
`max`). `timestamp` is ISO 8601 or epoch milliseconds and defaults to now. `unit` is free text that
is shown, not converted.

## Result

Each datum is checked on its own. The answer is `200` when at least one was stored; its `data` says
how many, and lists every refused datum by its index:

```json
{
  "success": true,
  "data": { "accepted": 2, "rejected": [{ "index": 2, "reason": "timestamp: more than 14 days old" }] }
}
```

The new series appear under **Monitoring**, **Custom metrics** within a minute.

## When datums are refused

- A datum more than 14 days old or more than 2 hours ahead ("timestamp: more than 2 hours ahead"),
  with not exactly one of `value`, `values` and `statistics` ("Exactly one of value, values or
  statistics"), or with more than ten dimensions, is listed in `rejected`.
- A new series past the organization's **Custom metric series** quota is listed with "series limit:
  the organization already has … active series (quota monitoring.custom-metric-series)". A series
  counts as active while it received a datapoint in the last 15 days.
- When no datum was stored, the answer is `400` "No datum was stored: …" with the same `rejected`
  list.
- A namespace starting with `DCLOUD/`, `EWS/` or `AWS/` (in any case), or with characters other
  than letters, digits and `. _ / # : -`, refuses the whole request with `400`, for example
  "namespace: Namespaces starting with DCLOUD/, EWS/ or AWS/ are reserved".
- A request that would take your organization past 20000 datums in a minute is refused with `429`
  "At most 20000 datums a minute per organization; send fewer, or aggregate before sending". Each
  web server of the platform counts this on its own.
- A request holds 1 to 1000 datums.

## Related

- [Chart custom metrics](chart-custom-metrics.md)
- [Alarm on a custom metric](alarm-on-a-custom-metric.md)
- `monitoring.custom-metrics.put` · `dcloud monitoring custom-metrics put`
