Update Metric Value

Updates the latest value for a metric displayed in ActivitySmith widgets. If no metric uses the key yet, the first value creates one: the label comes from the key, numeric values get the number format, and text values get the string format. To choose a currency, percent, or unit format, create the metric first with PUT /metrics/{key} or in the web app. A deleted metric is not recreated by new values; the request returns 404 with code metric_deleted. Each account can have up to 100 metrics created through the API. Metric updates have an independent 300-requests-per-minute account allowance. They do not consume the Push Notification, badge, or Live Activity allowances.

POST https://activitysmith.com/api/metrics/{key}/value

Authentication#

Use your API key in the request header.

Authorization: Bearer $YOUR_API_KEY

Parameters#

key#

path parameter. Required.

Metric key. A key that has never been used creates the metric. 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#

import ActivitySmith from "activitysmith";
const activitysmith = new ActivitySmith({
  apiKey: process.env.ACTIVITYSMITH_API_KEY,
});
await activitysmith.metrics.update("deploy.success_rate", 99.9);

Bodyapplication/json

Latest metric value to display in widgets.

valuenumber or string (Min Length: 1; Max Length: 64)required

timestampstring<date-time>

Optional ISO timestamp for when the metric value was measured. Defaults to the server receive time.

Additional Properties: false

{
  "value": 42
}

Responses#

200#

Metric value updated

Content type: application/json

Schema: MetricValueUpdateResponse#

successbooleanrequired

createdboolean

true when this request created the metric because no metric used the key yet.

Additional Properties: false

success

{
  "success": true
}

created

{
  "success": true,
  "created": true
}

400#

Bad request (invalid key or value)

Content type: application/json

Schema: MetricError#

errorstringrequired

messagestring

Additional Properties: true

invalid value

{
  "error": "value must be a finite number"
}

404#

Metric deleted or not found

Content type: application/json

Schema: MetricError

not found

{
  "error": "Metric not found"
}

deleted

{
  "error": "Metric deleted",
  "code": "metric_deleted",
  "message": "The metric with this key was deleted. Create it again before sending new values.",
  "key": "deploy.success_rate"
}

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