Tasks

Define background tasks that are triggered via fan-out from cron jobs or manually from the dashboard.

API

task(name: string, handler: Function, options?: Options)

name — unique identifier for this task.

handler — async function receiving context and payload.

options — optional retries, timeout, concurrency (same as cron).

Defining a Task

Tasks are defined the same way as crons, but without a schedule. They receive a payload as the second argument:

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

export const sendEmail = task(
  "send-email",
  async (ctx, { id }: { id: string }) => {
    const email = await getEmail(id);
    await deliver(email);
    ctx.log(`Sent email to ${email.to}`);
  },
  { retries: 2, timeout: "15s" }
);

Fan-Out Pattern

Use ctx.task() inside a cron to dispatch independent sub-tasks. Each task runs with its own retries, timeout, and tracking:

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

// Parent cron — runs every 15 minutes
export const sendEmails = cron(
  "send-emails",
  "*/15 * * * *",
  async (ctx) => {
    const pending = await getPendingEmails();

    for (const email of pending) {
      await ctx.task("send-email", { id: email.id });
    }

    ctx.log(`Dispatched ${pending.length} emails`);
    return { dispatched: pending.length };
  }
);

// Child task — runs independently per email
export const sendEmail = task(
  "send-email",
  async (ctx, { id }: { id: string }) => {
    const email = await getEmail(id);
    await deliver(email);
    ctx.log(`Sent email to ${email.to}`);
  },
  { retries: 2, timeout: "15s" }
);

How Fan-Out Works

1. The cron handler calls ctx.task("send-email", payload) which collects the task request in memory.

2. When the cron handler finishes, the SDK returns the collected tasks in the response.

3. The platform creates a child execution for each task, linked to the parent.

4. Each child task is dispatched independently via the queue with its own retry policy.

5. Child tasks appear nested under the parent execution in the dashboard.

Note: Tasks can also be triggered manually from the Pingback dashboard. Navigate to your task in the dashboard and click "Run" to dispatch it with a custom payload — useful for testing and one-off executions.