Skip to content

Test a function as a background job ​

A function runtime can run without a visitor request, as a background job, with up to 14 minutes instead of 5 seconds. This page runs a function once the way a job would, so you can check that it handles the job event and finishes inside its deadline before anything starts it on a schedule.

Nothing on this page changes the live site. A test run is not a visitor request and is never retried.

Function runtimes are managed through an agent (MCP) only; there are no CLI or HTTP routes for them yet. The job run you produce can be read in the web app, with the CLI, or through the API.

Throughout, the distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38) and the function runtime is 01JBQZ8XKT4A9WN2CDEFGH5RM7, already built. If you have none, start with Add an endpoint.

1. Handle the job event ​

A job reaches your handler as a POST to /_jobs/{kind}/{name} with a JSON string body. Route on the path, and key any side effect on job_id, because a job can run more than once:

js
function handler(request, env) {
  if (request.path.startsWith('/_jobs/')) {
    const job = JSON.parse(request.body);
    // job.type is cron, queue or workflow; job.job_id is stable across retries.
    console.log(`job ${job.job_id} attempt ${job.attempt}`);
    return { statusCode: 200, body: JSON.stringify({ done: true }) };
  }
  return { statusCode: 404, body: 'not found' };
}

Answer 2xx when the work is done. A 5xx asks for a retry; a 4xx says the job cannot succeed and should not be retried. The event shape is in Function runtimes.

2. Set the deadline ​

Jobs get 300 seconds unless the function asks for something else, from 1 to 840 seconds. Changing it does not rebuild the function.

text
On acme-marketing, give function 01JBQZ8XKT4A9WN2CDEFGH5RM7 a background timeout of
600 seconds. Do not change its source.

The agent runs edge_function_update with only background_timeout_seconds. The answer has "job_id": null, because nothing was rebuilt, and "background_timeout_seconds": 600.

3. Run it as a cron job ​

text
Run function 01JBQZ8XKT4A9WN2CDEFGH5RM7 on acme-marketing once as a cron job and show
me the job id, status, duration and stderr.

The agent runs edge_function_invoke with trigger: "cron". It sends the event a real cron would, with "test": true added, to the background runner and waits for the result:

json
{
  "trigger": "cron",
  "job_id": "job_01M4X7T2K9Q0V3B8N6C5D1E2F3",
  "job_status": "succeeded",
  "deadline_seconds": 600,
  "status_code": 200,
  "body": "{\"done\":true}",
  "stderr": "job job_01M4X7T2K9Q0V3B8N6C5D1E2F3 attempt 1",
  "duration_ms": 1840,
  "fetch_count": 0,
  …
}

To test a queue consumer, ask for trigger: "queue" and pass the messages the job would carry, for example {"messages": [{"id": "msg_1", "body": {"order": 42}}]}. Use trigger: "workflow" for a workflow step.

If the run fails with deadline_exceeded, raise the deadline in step 2 or do less in one run. fuel_exhausted means the work is too heavy for one run at any deadline you can set.

4. Read the job run ​

In the web app, open Distributions and select acme-marketing. Background jobs in the panel lists recent runs with their status and duration; a test run is labelled Test run.

text
List the background job runs on acme-marketing that failed.
bash
edge jobs ls acme-marketing --status failed
bash
curl -s "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/jobs?status=failed" \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_job_runs. Each run has its status, error_code, fuel_used, duration_ms and fetch_count. Runs are kept for 30 days.

For what the function printed, ask the agent for its runtime logs from that job: it runs edge_function_logs with the job_id.

Next ​

Read Background jobs for why a job can run twice and which failures are retried.