Background Execution

Conceptual

Long-running, scheduled and event-triggered work.

Tasks do not require an open connection. Submit an objective, disconnect, and collect the outcome later via polling, webhook or stream replay.

Execution modes#

Mode	Trigger	Typical duration
Interactive	API call with an open stream	Seconds to minutes
Detached	API call, result collected later	Minutes to hours
Scheduled	Cron expression or interval	Recurring
Event-driven	Inbound webhook or connector event	On demand
Continuous	Standing objective re-evaluated on new data	Ongoing, budget-capped

Scheduled monitoring task

await pimsy.tasks.create({
  objective:
    class="tok-str">"Every weekday at class="tok-num">07:class="tok-num">00 UTC, summarize overnight error-rate anomalies across production services " +
    class="tok-str">"and post a digest to the incident channel. Escalate only if p99 error rate exceeds class="tok-num">2%.",
  schedule: { cron: class="tok-str">"class="tok-num">0 class="tok-num">7 * * class="tok-num">1-class="tok-num">5", timezone: class="tok-str">"UTC" },
  capabilities: [class="tok-str">"connector.datadog", class="tok-str">"connector.slack"],
  budget: { steps: class="tok-num">25, usd: class="tok-num">2.5 },
  approvals: { required: [] }
});

Collecting results#

Poll GET /v1/tasks/{id} for status and artifacts.
Receive a callback on completion, failure or approval request — see Webhooks.
Replay the event log from any offset — see Streaming.

Last updated 2026-09-04