Live Activities for backend workflows and live system state

Q: Do I need to store activity_id for every Live Activity?

No. If you use stateless stream mode with a stable `stream_key`, ActivitySmith can manage the Live Activity for you. Store `activity_id` only when you want direct lifecycle control over `start`, `update`, and `end` calls.

Q: What is the difference between stream_key mode and start/update/end lifecycle control?

Use `stream_key` mode when you want the simplest integration and do not want to keep state between runs. Use `start`, `update`, and `end` when your backend already has a natural place to store `activity_id` and you want precise control over each lifecycle step.

Show deploys, jobs, automations, AI agent runs, and infrastructure metrics on your lock screen with a simple API call.

1
await activitysmith.liveActivities.start({
2
  content_state: {
3
    title: "API Deployment",
4
    subtitle: "npm i",
5
    number_of_steps: 5,
6
    current_step: 3,
7
    type: "segmented_progress",
8
  },
9
});

Node SDK

Three Live Activity types

Metrics

Best for live operational stats like server CPU and memory, queue depth, replica lag, and other small sets of related runtime signals.

Read how to track VPS system health on your lock screen with a cron job

Segmented Progress

Best for step-based workflows like deployments, backups, ETL pipelines, migrations, and operator checklists.

Read how to track deployment progress on your lock screen

Progress

Best for continuous jobs like uploads, reindexes, syncs, timers, charging sessions, and other work tracked as a percentage or numeric range.

Two ways to drive Live Activities

When working with Live Activities via our API, you have two approaches tailored to different needs. First, the stateless mode is the simplest path - simply stream updates using one API call, then end it when the work is done. See the stateless Live Activity stream mode changelog for the release details.

This is ideal if you want minimal complexity, perfect for automated workflows like cron jobs.

In contrast, if you need precise lifecycle control, we have you covered with start, update, and end API methods.

In the following sections, we'll break down how to implement each method so you can choose what fits your use case best.

Let ActivitySmith manage the Live Activity for you

Send the latest state for a stable stream_key. If the Live Activity does not exist yet, ActivitySmith starts it. If it already exists, ActivitySmith updates it.

You do not need to store activity_id or manage the lifecycle yourself. The metrics Live Activities release shows the same pattern applied to runtime stats.

1
const status = await activitysmith.liveActivities.stream("prod-web-1", {
2
  content_state: {
3
    title: "Server Health",
4
    subtitle: "prod-web-1",
5
    type: "metrics",
6
    metrics: [
7
      { label: "CPU", value: 9, unit: "%" },
8
      { label: "MEM", value: 45, unit: "%" },
9
    ],
10
  },
11
});

View on GitHub

Node SDK

View Live Activities docs

Manual lifecycle control when you need it

Use start, update, and end when you want to manage a specific Live Activity instance yourself. start returns activity_id, then your backend decides exactly when to update or dismiss it.

Segmented Progress lifecycle

Use this when work moves through discrete steps and the current stage matters more than a raw percentage. The GitHub Action integration is a good example for deployment workflows.

Start

1
const start = await activitysmith.liveActivities.start({
2
  content_state: {
3
    title: "Nightly database backup",
4
    subtitle: "create snapshot",
5
    number_of_steps: 3,
6
    current_step: 1,
7
    type: "segmented_progress",
8
    color: "yellow",
9
  },
10
  channels: ["devs", "ops"], // Optional
11
});
12
13
const activityId = start.activity_id;

View on GitHub

Node SDK

Update

1
const update = await activitysmith.liveActivities.update({
2
  activity_id: activityId,
3
  content_state: {
4
    title: "Nightly database backup",
5
    subtitle: "upload archive",
6
    current_step: 2,
7
  },
8
});

View on GitHub

Node SDK

End

1
const end = await activitysmith.liveActivities.end({
2
  activity_id: activityId,
3
  content_state: {
4
    title: "Nightly database backup",
5
    subtitle: "verify restore",
6
    current_step: 3,
7
    auto_dismiss_minutes: 2,
8
  },
9
});

View on GitHub

Node SDK

Progress lifecycle

Use this when progress is continuous and a percentage or numeric range is the clearest signal.

Start

1
const start = await activitysmith.liveActivities.start({
2
  content_state: {
3
    title: "EV Charging",
4
    subtitle: "Added 30 mi range",
5
    type: "progress",
6
    percentage: 15,
7
    color: "lime",
8
  },
9
});
10
11
const activityId = start.activity_id;

View on GitHub

Node SDK

Update

1
await activitysmith.liveActivities.update({
2
  activity_id: activityId,
3
  content_state: {
4
    title: "EV Charging",
5
    subtitle: "Added 120 mi range",
6
    percentage: 60,
7
  },
8
});

View on GitHub

Node SDK

End

1
await activitysmith.liveActivities.end({
2
  activity_id: activityId,
3
  content_state: {
4
    title: "EV Charging",
5
    subtitle: "Added 200 mi range",
6
    percentage: 100,
7
    auto_dismiss_minutes: 2,
8
  },
9
});

View on GitHub

Node SDK

Metrics lifecycle

Use this when you want a small set of live stats visible, such as server health, queue pressure, or database load.

Start

1
const start = await activitysmith.liveActivities.start({
2
  content_state: {
3
    title: "Server Health",
4
    subtitle: "prod-web-1",
5
    type: "metrics",
6
    metrics: [
7
      { label: "CPU", value: 9, unit: "%" },
8
      { label: "MEM", value: 45, unit: "%" },
9
    ],
10
  },
11
});
12
13
const activityId = start.activity_id;

View on GitHub

Node SDK

Update

1
await activitysmith.liveActivities.update({
2
  activity_id: activityId,
3
  content_state: {
4
    title: "Server Health",
5
    subtitle: "prod-web-1",
6
    type: "metrics",
7
    metrics: [
8
      { label: "CPU", value: 76, unit: "%" },
9
      { label: "MEM", value: 52, unit: "%" },
10
    ],
11
  },
12
});

View on GitHub

Node SDK

End

1
await activitysmith.liveActivities.end({
2
  activity_id: activityId,
3
  content_state: {
4
    title: "Server Health",
5
    subtitle: "prod-web-1",
6
    type: "metrics",
7
    metrics: [
8
      { label: "CPU", value: 7, unit: "%" },
9
      { label: "MEM", value: 38, unit: "%" },
10
    ],
11
    auto_dismiss_minutes: 2,
12
  },
13
});

View on GitHub

Node SDK

Integrate in minutes

Pick your stack and start triggering Live Activities from your backend in a few lines of code.

Node.js SDK

Python SDK

Go SDK

PHP SDK

Ruby SDK

ActivitySmith CLI

Frequently asked questions

Can I trigger iOS Live Activities from a backend or cron job?

Yes. ActivitySmith is built for backend-triggered Live Activities, so you can start or stream updates from APIs, cron jobs, CI pipelines, workers, scripts, and automations without building your own iOS app.

Do I need to store activity_id for every Live Activity?

No. If you use stateless stream mode with a stable stream_key, ActivitySmith can manage the Live Activity for you. Store activity_id only when you want direct lifecycle control over start, update, and end calls.

What is the difference between stream_key mode and start/update/end lifecycle control?

Use stream_key mode when you want the simplest integration and do not want to keep state between runs. Use start, update, and end when your backend already has a natural place to store activity_id and you want precise control over each lifecycle step.

Can I use ActivitySmith Live Activities for deployments, CI jobs, and AI agent runs?

Yes. Common use cases include deployments, build pipelines, cron jobs, infrastructure metrics, ETL runs, and AI agent workflows where teams want persistent lock-screen visibility while work is in progress.

Do I need to build my own iOS app to send Live Activities?

No. ActivitySmith provides the iOS app and delivery plumbing. Your backend sends the event data, and ActivitySmith delivers the Live Activity to your team's paired iPhone and iPad devices.

Track backend work and live system state on your team's iOS devices

Give your team one persistent view of deploys, jobs, automations, and metrics. When the work is done, the Live Activity is automatically dismissed. Pair it with push notifications for final outcomes and one-off alerts.

Start Today Book a Demo