Tasks

Background functions triggered via fan-out, programmatic triggers, or the dashboard. Unlike crons, tasks have no schedule — they run on demand.

Quick Example

import { task } from "@usepingback/next";

export const sendEmail = task("send-email", async (ctx) => {
  const { to, subject, body } = ctx.payload as {
    to: string;
    subject: string;
    body: string;
  };

  ctx.log(`Sending email to ${to}`);
  await emailClient.send({ to, subject, body });
}, { retries: 3, timeout: "30s" });

Registration

Parameter	Type	Required	Description
`name`	string	Yes	Unique identifier for this task.
`handler`	function	Yes	Function to execute. Receives context and payload.
`options`	object	No	Configuration (see below).

Options

Option	Type	Default	Description
`retries`	0–10	0	Retry attempts with exponential backoff.
`timeout`	string	"30s"	Max execution time.
`concurrency`	1–10	1	Max concurrent executions.

Payload

Tasks receive a payload — arbitrary JSON data passed when the task is triggered. The payload is available via the context object. SDKs may support typed payloads for automatic deserialization.

Execution Lifecycle

A task is triggered (via fan-out, trigger(), or dashboard).
A pending execution is created with the payload.
The execution is dispatched to the job queue.
Your handler runs with the context and payload.
On failure, retried with exponential backoff if retries > 0.