← Back to API docs

Tasks API

A tasks instance holds queues. A task is one JSON payload. A push queue delivers each task to a function, a channel or a webhook, and retries it until the target accepts it or its attempts run out. A pull queue holds tasks for your own workers to lease.

Create a queue and add a task

Create a tasks instance — here jobs — in the console or with MCP's create_instance. Queues are created on its Queues tab, or over the API:

curl -X POST https://api.altengine.net/v1/tasks/jobs/queues \
  -H "Authorization: Bearer $ALTENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"emails","target":{"function":"app/send-receipt"},"ratePerSecond":5}'

curl -X POST https://api.altengine.net/v1/tasks/jobs/queues/emails/tasks \
  -H "Authorization: Bearer $ALTENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"orderId":"o-1041"},"name":"receipt-o-1041","delay":60}'

# → 201 { "tasks": [{ "ok": true, "id": "0mvpn7bai3f9c2e81d4a7", "name": "receipt-o-1041",
#                     "state": "scheduled", "runAt": 1793042520000 }] }

The function send-receipt in functions instance app is called a minute later. A task with no delay runs within about a second. Every instance has a queue named default.

From a function granted tasks, the same add is one call — answer the request now and do the slow work in the background:

await env.tasks.add({ instance: "jobs" }, "emails", { payload: { orderId }, name: `receipt-${orderId}` });
return Response.json({ ok: true });

Queues

POST /v1/tasks/{instance}/queues creates one: {name, …settings}. PATCH /v1/tasks/{instance}/queues/{queue} changes only the settings you send.

Across all its queues, an instance has at most 50 deliveries in flight.

Adding tasks

POST /v1/tasks/{instance}/queues/{queue}/tasks takes one task, an array, or {"tasks": [...]} — up to 100.

Each result in tasks is {ok: true, id, name, state, runAt} or {ok: false, code: "TASK_EXISTS", id, name, message}, in request order. The call answers 201 when at least one task was added, and 409 when none was — the same results, plus an error naming the first refusal. A push queue with no target refuses a task that has none of its own (400 NO_TARGET), and nothing in that call is added.

Names make an add idempotent

A name already used in the queue is refused with TASK_EXISTS and the existing task's id — for as long as that task's record is kept, finished or not: retentionDays after it finished, 7 by default. Name a task after the thing it does (receipt-o-1041) and a retried request cannot add it twice.

What a target receives

A function and a webhook both get a POST with this body:

{ "task": { "id": "0mvpn7bai3f9c2e81d4a7", "queue": "emails", "name": "receipt-o-1041",
            "attempt": 1, "maxAttempts": 10, "runAt": 1793042520000, "createdAt": 1793042460000,
            "deadlineAt": 1793043120000, "source": "api", "depth": 0, "params": null,
            "deadLetterOf": null },
  "payload": { "orderId": "o-1041" } }

source says where the task came from: api, console, mcp, function, datastore, blob, mailbox, deadletter or rerun.

The deadline

A function or webhook target has until task.deadlineAt (epoch ms) to answer: the queue's deadlineSeconds after the attempt starts, 600 by default, or the task's own. Past it the attempt counts as failed and is retried. The target is not stopped: its slot stays taken and the retry waits until it returns, so maxConcurrent is never exceeded and a task never runs beside itself. The timed-out attempt records what the target finally answered. For work longer than 14 minutes, use a pull queue, whose worker extends its lease.

What the answer means

A target is looked up again on every attempt, so one deleted after the task was added fails it then.

export default {
  async fetch(request, env) {
    const { task, payload } = await request.json();
    if (await alreadySent(task.id)) return new Response("dup");   // at-least-once
    await sendReceipt(payload.orderId);
    return new Response("sent");                                  // 2xx: done
  },
};

Verifying a webhook

Every webhook delivery carries x-altengine-timestamp (ms) and x-altengine-signature: v1=<hex>, an HMAC-SHA256 keyed with the instance's signing key — the whole string, whsec_ prefix included — over <timestamp>.<raw body>. Owners reveal and rotate the key in the instance's Settings, or with MCP's tasks_reveal_webhook_secret and tasks_rotate_webhook_secret.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, rawBody, secret) {
  const ts = req.headers["x-altengine-timestamp"];
  const want = "v1=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const got = req.headers["x-altengine-signature"] ?? "";
  return got.length === want.length && timingSafeEqual(Buffer.from(got), Buffer.from(want))
    && Math.abs(Date.now() - Number(ts)) < 5 * 60_000;   // reject replays
}

Rotating takes effect on the next delivery — update the receiver straight away. A webhook URL is https, with no username or password, at most 2,048 characters.

Retries

After the nth failed attempt the wait is minBackoffSeconds × 2^(n−1). Past maxDoublings it grows by the last doubled step each time instead, and never exceeds maxBackoffSeconds. With the defaults: 10 s, 20 s, 40 s … 2,560 s before the tenth and last attempt.

Steering retries from the target

A function or webhook can change what happens next with headers on its answer:

// the record this task needs is not there yet: try again in a minute, without using an attempt
return new Response("waiting", { status: 503, headers: { "x-task-retry": "defer", "retry-after": "60" } });

maxAgeSeconds still ends a task that is retried or deferred past it. Set the queue's targetControl to false and these headers are ignored.

Watching and managing tasks

In the console, a tasks instance's Queues tab shows each queue's counts by state; the Tasks tab lists them by queue and state, opens one with its attempts, and runs, retries or cancels it. The same operations over the API:

GET …/queues/{queue}/tasks lists one page without payloads. Filter with state or name; page with limit (50 by default, at most 200) and the cursor from the previous page — null is the last page. Scheduled, running and leased tasks come soonest first, finished ones latest first, and with no state newest first. GET …/tasks/{id} returns one task with its payload, result, and every attempt with its status and error. A queue's counts by state stop at 10,000; a state listed in capped has at least that many.

Pull queues

A queue with "mode": "pull" never delivers. Your worker leases tasks, does the work, and acknowledges each one:

POST /v1/tasks/jobs/queues/thumbnails/lease
{ "count": 10, "leaseSeconds": 120 }
→ { "tasks": [{ "id": "0mvpn7bai…", "payload": { "key": "blob:9f3c…:7a1b…" }, "attempts": 1,
                "leaseId": "c3a9…", … }] }

POST /v1/tasks/jobs/tasks/0mvpn7bai…/ack
{ "leaseId": "c3a9…", "result": { "width": 320 } }

A lease that runs out without an ack counts as a failed attempt, and the task is retried with backoff. Every call after that with the old leaseId answers 409 LEASE_LOST, so a slow worker cannot finish a task another worker now holds.

Dead-letter queues

Set a queue's deadLetterQueue to another queue in the same instance, which must already exist. When a task fails, a copy is added there: the same payload and params, no name, and task.deadLetterOf set to the failed task's id. The dead-letter queue delivers it to its own target with its own retry policy, or, as a pull queue, holds it for you to lease.

Triggers

Other services can add tasks as things happen. A trigger names a queue as <tasks-instance>/<queue>; the queue's target runs the task, at the queue's rate and with its retries.

The queue must exist when the rule is saved, and must have a target or be a pull queue. A rule's params reach the target as task.params. A chain of triggers more than 8 deep — a function writing the document that triggered it — is cut.

From a function

Grant a function tasks and it gets env.tasks. Methods return the value REST wraps — add the array of results, get the task — and take the same bodies and limits.

Endpoints and grants

Every call takes an organization API key with a grant on the instance. An end-user identity token is refused. Changing a queue needs full: its target runs every task with that target's own access.

Limits and settings

Change retentionDays and rateLimit in the instance's Settings, or with MCP's patch_instance_config.

What it costs

Tasks added, deliveries to a channel or webhook target (every attempt), and the data the instance keeps, averaged over the month. A delivery to a function bills as a function invocation instead, and one to a channel also bills as a channel message. See pricing for the numbers.

Testing locally

The emulator serves the same API, env.tasks, triggers and MCP tools, and delivers a task within about a second of it falling due, logging every attempt to the terminal.

altengine dev     # http://127.0.0.1:9191

Where it differs:

• A tasks instance is created on first use.
• Purging a queue and deleting one finish at once; pending is always false.
• A trigger rule change applies immediately, not within about 30 seconds.
• A trigger event that cannot be queued is logged to the terminal, not shown as a console notice.
• Revealing and rotating the webhook key are not limited to owners, and MCP scopes are not checked.

From an AI agent

The MCP server exposes tasks directly: tasks_list_queues, tasks_set_queue (create or change), tasks_add, tasks_list, tasks_get, tasks_run, tasks_cancel, and an agent can be a pull worker itself with tasks_lease, tasks_ack and tasks_release. tasks_purge_queue and tasks_delete_queue need full plus confirm: true. The resource docs://tasks/guide covers targets, retries and triggers.