Skip to main content

​
Installation

Install the ActivitySmith Python SDK with pip:
Python
pip install activitysmith

​
Usage

  1. Create an API key
  2. Set ACTIVITYSMITH_API_KEY or pass it directly to ActivitySmith.
  3. Reuse the client anywhere you send pushes or Live Activity updates.
Create the client once:
Python
import os
from activitysmith import ActivitySmith

activitysmith = ActivitySmith(api_key=os.environ.get("ACTIVITYSMITH_API_KEY", "YOUR-API-KEY"))

​
Send a Push Notification

Use activitysmith.notifications.send when a deploy finishes, a customer upgrades, or a background job needs attention. title is required. message and subtitle are optional. Push notification example for a new subscription event
Python
activitysmith.notifications.send(
    {
        "title": "New subscription 💸",
        "message": "Customer upgraded to Pro plan",
    }
)

​
Rich Push Notifications with Media

Rich push notification with image
Python
activitysmith.notifications.send(
    {
        "title": "Homepage ready",
        "message": "Your agent finished the redesign.",
        "media": "https://cdn.example.com/output/homepage-v2.png",
        "redirection": "https://github.com/acme/web/pull/482",
    }
)
Send images, videos, or audio with your push notifications, press and hold to preview media directly from the notification, then tap through to open the linked content. Rich push notification with audio What will work:
  • direct image URL: .jpg, .png, .gif, etc.
  • direct audio file URL: .mp3, .m4a, etc.
  • direct video file URL: .mp4, .mov, etc.
  • URL that responds with a proper media Content-Type, even if the path has no extension
media can be combined with redirection, but not with actions.

​
Actionable Push Notifications

Actionable push notification with redirection and actions Push notification redirection and actions are optional and can be used to redirect the user to a specific URL when they tap the notification or to trigger a specific action when they long-press the notification. Webhooks are executed by ActivitySmith backend.
Python
activitysmith.notifications.send(
    {
        "title": "New subscription 💸",
        "message": "Customer upgraded to Pro plan",
        "redirection": "https://crm.example.com/customers/cus_9f3a1d",
        "actions": [
            {
                "title": "Open CRM Profile",
                "type": "open_url",
                "url": "https://crm.example.com/customers/cus_9f3a1d",
            },
            {
                "title": "Start Onboarding Workflow",
                "type": "webhook",
                "url": "https://hooks.example.com/activitysmith/onboarding/start",
                "method": "POST",
                "body": {
                    "customer_id": "cus_9f3a1d",
                    "plan": "pro",
                },
            },
        ],
    }
)

​
Live Activities

Metrics Live Activity screenshot

There are three types of Live Activities:
  • metrics: best for live operational stats like server CPU and memory, queue depth, or replica lag
  • segmented_progress: best for step-based workflows like deployments, backups, and ETL pipelines
  • progress: best for continuous jobs like uploads, reindexes, and long-running migrations tracked as a percentage
When working with Live Activities via our API, you have two approaches tailored to different needs. First, the stateless mode is the simplest path - one API call can initiate or update an activity, and another ends it - no state tracking on your side. This is ideal if you want minimal complexity, perfect for automated workflows like cron jobs. In contrast, if you need precise lifecycle control, the classic approach offers distinct calls for start, updates, and end, giving you full control over the activity’s state. In the following sections, we’ll break down how to implement each method so you can choose what fits your use case best.

​
Simple: Let ActivitySmith manage the Live Activity for you

Use a stable stream_key to identify the system or workflow you are tracking, such as a server, deployment, build pipeline, cron job, or charging session. This is especially useful for cron jobs and other scheduled tasks where you do not want to store activity_id between runs.

​
Metrics

Metrics stream example

status = activitysmith.live_activities.stream(
    "prod-web-1",
    {
        "content_state": {
            "title": "Server Health",
            "subtitle": "prod-web-1",
            "type": "metrics",
            "metrics": [
                {"label": "CPU", "value": 9, "unit": "%"},
                {"label": "MEM", "value": 45, "unit": "%"},
            ],
        },
    },
)

​
Segmented progress

Segmented progress stream example

activitysmith.live_activities.stream(
    "nightly-backup",
    {
        "content_state": {
            "title": "Nightly Backup",
            "subtitle": "upload archive",
            "type": "segmented_progress",
            "number_of_steps": 3,
            "current_step": 2,
        },
    },
)

​
Progress

Progress stream example

activitysmith.live_activities.stream(
    "search-reindex",
    {
        "content_state": {
            "title": "Search Reindex",
            "subtitle": "catalog-v2",
            "type": "progress",
            "percentage": 42,
        },
    },
)
Call stream(...) again with the same stream_key whenever the state changes.

​
End a stream

Use this when the tracked process is finished and you no longer want the Live Activity on devices. content_state is optional here; include it if you want to end the stream with a final state. 
activitysmith.live_activities.end_stream(
    "prod-web-1",
    {
        "content_state": {
            "title": "Server Health",
            "subtitle": "prod-web-1",
            "type": "metrics",
            "metrics": [
                {"label": "CPU", "value": 7, "unit": "%"},
                {"label": "MEM", "value": 38, "unit": "%"},
            ],
        },
    },
)
If you later send another stream(...) request with the same stream_key, ActivitySmith starts a new Live Activity for that stream again. Stream responses include an operation field:
  • started: ActivitySmith started a new Live Activity for this stream_key
  • updated: ActivitySmith updated the current Live Activity
  • rotated: ActivitySmith ended the previous Live Activity and started a new one
  • noop: the incoming state matched the current state, so no update was sent
  • paused: the stream is paused, so no Live Activity was started or updated
  • ended: returned by end_stream(...) after the stream is ended

​
Advanced: Full lifecycle control

Use these methods when you want to manage the Live Activity lifecycle yourself:
  1. Call activitysmith.live_activities.start(...).
  2. Save the returned activity_id.
  3. Call activitysmith.live_activities.update(...) as progress changes.
  4. Call activitysmith.live_activities.end(...) when the work is finished.

​
Metrics Type

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

​
Start

Metrics start example

start = activitysmith.live_activities.start(
    {
        "content_state": {
            "title": "Server Health",
            "subtitle": "prod-web-1",
            "type": "metrics",
            "metrics": [
                {"label": "CPU", "value": 9, "unit": "%"},
                {"label": "MEM", "value": 45, "unit": "%"},
            ],
        },
    }
)

activity_id = start.activity_id

​
Update

Metrics update example

activitysmith.live_activities.update(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "Server Health",
            "subtitle": "prod-web-1",
            "type": "metrics",
            "metrics": [
                {"label": "CPU", "value": 76, "unit": "%"},
                {"label": "MEM", "value": 52, "unit": "%"},
            ],
        },
    }
)

​
End

Metrics end example

activitysmith.live_activities.end(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "Server Health",
            "subtitle": "prod-web-1",
            "type": "metrics",
            "metrics": [
                {"label": "CPU", "value": 7, "unit": "%"},
                {"label": "MEM", "value": 38, "unit": "%"},
            ],
            "auto_dismiss_minutes": 2,
        },
    }
)

​
Segmented Progress Type

Use segmented_progress for jobs and workflows that move through clear steps or phases. It fits jobs like backups, deployments, ETL pipelines, and checklists. number_of_steps is dynamic, so you can increase or decrease it later if the workflow changes.

​
Start

Segmented progress start example

start = activitysmith.live_activities.start(
    {
        "content_state": {
            "title": "Nightly database backup",
            "subtitle": "create snapshot",
            "number_of_steps": 3,
            "current_step": 1,
            "type": "segmented_progress",
            "color": "yellow",
        },
    }
)

activity_id = start.activity_id

​
Update

Segmented progress update example

activitysmith.live_activities.update(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "Nightly database backup",
            "subtitle": "upload archive",
            "number_of_steps": 3,
            "current_step": 2,
        },
    }
)

​
End

Segmented progress end example

activitysmith.live_activities.end(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "Nightly database backup",
            "subtitle": "verify restore",
            "number_of_steps": 3,
            "current_step": 3,
            "auto_dismiss_minutes": 2,
        },
    }
)

​
Progress Type

Use progress when the state is naturally continuous. It fits charging, downloads, sync jobs, uploads, timers, and any flow where a percentage or numeric range is the clearest signal.

​
Start

Progress start example

start = activitysmith.live_activities.start(
    {
        "content_state": {
            "title": "EV Charging",
            "subtitle": "Added 30 mi range",
            "type": "progress",
            "percentage": 15,
        }
    }
)

activity_id = start.activity_id

​
Update

Progress update example

activitysmith.live_activities.update(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "EV Charging",
            "subtitle": "Added 120 mi range",
            "percentage": 60,
        }
    }
)

​
End

Progress end example

activitysmith.live_activities.end(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "EV Charging",
            "subtitle": "Added 200 mi range",
            "percentage": 100,
            "auto_dismiss_minutes": 2,
        }
    }
)

​
Live Activity Action

Just like Actionable Push Notifications, Live Activities can have a button that opens provided URL in a browser or triggers a webhook. Webhooks are executed by the ActivitySmith backend. Live Activity with action

​
Open URL action

Python
start = activitysmith.live_activities.start(
    {
        "content_state": {
            "title": "Deploying payments-api",
            "subtitle": "Running database migrations",
            "number_of_steps": 5,
            "current_step": 3,
            "type": "segmented_progress",
        },
        "action": {
            "title": "Open Workflow",
            "type": "open_url",
            "url": "https://github.com/acme/payments-api/actions/runs/1234567890",
        },
    }
)

activity_id = start.activity_id

​
Webhook action

Python
activitysmith.live_activities.update(
    {
        "activity_id": activity_id,
        "content_state": {
            "title": "Reindexing product search",
            "subtitle": "Shard 7 of 12",
            "number_of_steps": 12,
            "current_step": 7,
        },
        "action": {
            "title": "Pause Reindex",
            "type": "webhook",
            "url": "https://ops.example.com/hooks/search/reindex/pause",
            "method": "POST",
            "body": {
                "job_id": "reindex-2026-03-19",
                "requested_by": "activitysmith-python",
            },
        },
    }
)

​
Channels

Target specific channels when sending a push or starting a Live Activity.
Python
activitysmith.notifications.send(
    {
        "title": "New subscription 💸",
        "message": "Customer upgraded to Pro plan",
        "channels": ["ios-builds", "engineering"],
    }
)

activitysmith.live_activities.start(
    {
        "channels": ["ios-builds"],
        "content_state": {
            "title": "Nightly database backup",
            "number_of_steps": 3,
            "current_step": 1,
            "type": "segmented_progress",
        },
    }
)

​
Error Handling

Wrap API calls with try/except. The SDK raises exceptions for non-2xx responses. Rate limit errors use the error and message fields, and Live Activity limit errors include limit and active. See Rate Limits for details.

​
Additional Resources

PyPI Package

Install the ActivitySmith Python SDK from PyPI

Source Code

View the Python SDK source on GitHub