Fire a Sume schedule from a decision, not a clock: API trigger

Use the API-call trigger. With it, an external system decides when a run starts instead of a clock, which is what you want when a decision model says whether today is worth a run. The schedule needs status of active and api_trigger_enabled of true, and your key needs actions:read and actions:write. Then POST /v1/actions/{action_id}/runs returns 202 with a receipt.

What the trigger needs

Service-account keys cannot create Action runs and fail with 403 insufficient_scope. Keys created before the trigger shipped lack the scopes and must be replaced, since scopes cannot be added to an existing key.

import os
import requests


def fire(action_id: str, day: str, worth_it: bool) -> str | None:
    if not worth_it:
        return None
    r = requests.post(
        f"https://api.sume.com/v1/actions/{action_id}/runs",
        headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
                 "Idempotency-Key": f"{action_id}-{day}"},
        json={},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["id"]

One decision, one run

Key the idempotency header to the decision, such as the schedule id and the day. If your service retries after a timeout, the receipt comes back with idempotency_hit of true instead of a second run. The schedule's saved spend cap still applies to the run.

Check the docs before you ship

Sume's limits and field names change faster than blog posts do. Read the linked docs pages for the current request fields before you ship, and send a dry_run or a low spend cap on your first real call.