Create or Update Metric

Creates a metric for widgets, or updates the fields sent for an existing metric. Omitted fields keep their current values, so repeating the same request does not change the metric. Changing between the string format and a numeric format clears the latest value. Shares the metric account allowance of 300 requests per minute and is not a billable metric update.

PUT https://activitysmith.com/api/metrics/{key}

Authentication#

Use your API key in the request header.

Authorization: Bearer $YOUR_API_KEY

Parameters#

key#

path parameter. Required.

Metric key. Lowercase letters, numbers, dots, underscores, and dashes are allowed.

Type: string

Min Length: 1; Max Length: 64; Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$

Request examples#

curl -X PUT "https://activitysmith.com/api/metrics/mrr" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "MRR",
    "format": "currency",
    "currency_code": "USD"
  }'

Bodyapplication/json

Metric definition. Omitted fields keep their current values, or use defaults for a new metric: a label made from the key and the number format.

labelstring

Name shown on the widget.

Min Length: 1

Max Length: 80

formatstring

How widgets display the value: number (1,234), currency (requires currency_code), percent (send 99.9 to show 99.9%), unit (a number with a unit suffix, such as 120 ms), or string (text up to 64 characters). Defaults to number for a new metric.

Enum: ["number","currency","percent","unit","string"]

currency_codestring

3-letter ISO 4217 currency code, such as USD. Required for the currency format.

Pattern: ^[A-Za-z]{3}$

unitstring

Unit suffix for the unit format, such as ms or GB.

Max Length: 16

unit_spacingstring

For the unit format: none shows 120ms, space shows 120 ms.

Enum: ["none","space"]

Additional Properties: false

{
  "label": "MRR",
  "format": "currency",
  "currency_code": "USD"
}

Responses#

200#

Metric updated

Content type: application/json

Schema: MetricResponse#

metricMetricrequired

Additional Properties: false

updated

{
  "metric": {
    "public_id": "x8Kq2mVn4pLr7sTw9yZa",
    "key": "mrr",
    "label": "MRR",
    "format": "currency",
    "currency_code": "USD",
    "unit": null,
    "unit_spacing": "none",
    "latest_value": null,
    "latest_value_at": null,
    "created_at": "2026-10-26T09:00:00.000Z",
    "updated_at": "2026-10-26T09:00:00.000Z"
  }
}

201#

Metric created

Content type: application/json

Schema: MetricResponse

created

{
  "metric": {
    "public_id": "x8Kq2mVn4pLr7sTw9yZa",
    "key": "mrr",
    "label": "MRR",
    "format": "currency",
    "currency_code": "USD",
    "unit": null,
    "unit_spacing": "none",
    "latest_value": null,
    "latest_value_at": null,
    "created_at": "2026-10-26T09:00:00.000Z",
    "updated_at": "2026-10-26T09:00:00.000Z"
  }
}

400#

Bad request (invalid key or definition)

Content type: application/json

Schema: MetricError#

errorstringrequired

messagestring

Additional Properties: true

missing currency

{
  "error": "currency_code is required for currency metrics"
}

409#

Metric limit reached

Content type: application/json

Schema: MetricError

limit reached

{
  "error": "Metric limit reached",
  "code": "metric_limit_reached",
  "message": "This account already has 100 metrics. Delete unused metrics before adding more."
}

429#

Rate limit exceeded

Content type: application/json

Schema: RateLimitError#

codestring

Enum: ["rate_limited"]

errorstringrequired

messagestringrequired

Additional Properties: false

rate limited

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later."
}

Download the OpenAPI specification