---
title: "Create or update a metric definition"
method: PUT
path: "/v1/metric-alerts/definitions"
tags: ["Metric alerts"]
---

# Create or update a metric definition

`PUT /v1/metric-alerts/definitions`

Upserts by `(artifact_id, metric_id)`. Up to 10 metrics per artifact.

## Request body

- MetricDefinition
  - `artifact_id` string, required
  - `metric_id` string, required — Stable key referenced by rules. Letters, digits, `_`, `-`.
  - `label` string, required
  - `format` string — Display hint: `currency:USD`, `number`, `percent`.
  - `source` MetricSource, required — Where a metric value is read from.
    - `type` 'json_path' | 'table_count' | 'table_aggregate', required
    - `key` string — json_path: the sdk.json key to read.
    - `path` string — json_path: e.g. `$.revenue`, `$.totals.mrr`.
    - `table` string
    - `field` string
    - `fn` 'sum' | 'avg' | 'min' | 'max'
    - `where` object — Filter using the same operators as sdk.table().query().

## Response `200`

Saved

## Other responses

- `400` — Invalid request

---

[API](https://skmtc.net/shareout/apis/shareout-rest-api.md) · [All operations](https://skmtc.net/shareout/apis/shareout-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shareout/shareout-rest-api/versions/804359ead65a/schema)