Widgets

How It Works#

1. Send a value to a metric key with the API.
2. Add the widget to your iPhone Lock Screen and pick the metric.
3. The widget fetches the latest value about every 15 minutes. iOS manages the refresh schedule.

The first value sent to a new key creates the metric. ActivitySmith makes the label from the key, so deploy.success_rate becomes "Deploy success rate". Numeric values get the number format, and text values get the string format.

Creating a Metric#

A metric has one of these formats: number, currency, percent, unit, or string. To use currency, percent, or unit, create the metric before you send the first value. You can create a metric in three ways:

• In the web app.
• With the API, using PUT /metrics/{key}.
• With an AI agent, using the create_widget_metric tool of the MCP server.

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"
  }'

PUT /metrics/{key} creates the metric if the key is new. For an existing metric, it changes only the fields you send. You can send the same request each time your script starts.

For the full API reference, see Create or Update Metric.

Updating Metric Value#

Use the metric key when sending updates. Values can be numbers or strings.

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

For the full API reference, see Update Metric Value.

Deleted Metrics#

Values sent to the key of a deleted metric do not create the metric again. The API returns 404 with the code metric_deleted. To use the key again, create the metric again in the web app or with PUT /metrics/{key}.

Limits#

Each account can have up to 100 metrics created through the API. When the account reaches the limit, requests that would create a metric return 409 with the code metric_limit_reached. Delete metrics you do not use to add more.