Background Tasks

Execute long-running operations asynchronously without blocking API responses in Spala.

Background Tasks

Background tasks let you offload long-running or resource-intensive operations from your API endpoints. Instead of making users wait for a slow operation to complete, your endpoint can queue a background task and return an immediate response.

Spala Background Tasks monitor showing task status, filters, logs, and retry controls
The Background Tasks monitor shows queued, running, completed, failed, stopped, and timed-out work.

How Background Tasks Work

When a function triggers a background task:

1. The task is queued for asynchronous execution
2. The calling function continues immediately without waiting
3. The background task runs independently in its own execution context
4. Results and errors are logged for later inspection

This pattern is essential for operations like sending bulk emails, processing uploaded files, generating reports, or calling slow external APIs.

Creating a Background Task

Navigate to the Tasks section in the left sidebar

Click New Task and select Background Task

Give the task a descriptive name

Build the function that defines what the task does

Save the task

Triggering a Background Task

Background tasks are triggered from within other functions using the Run Task step. You can pass input data to the task as parameters.

// In your endpoint function:

// Step 1: Validate the upload
// ... validation logic ...

// Step 2: Run Task - "Process Upload"
// Pass the file path and user ID as parameters
// { filePath: vars.uploadPath, userId: vars.currentUser.id }

// Step 3: Respond to Client
// Return immediately with a 202 Accepted status
// { message: "Upload is being processed", taskId: result.taskId }

In the visual editor, drag a Run Task step into your function, select the target task, and map any input variables.

Passing Data to Background Tasks

When you trigger a background task, you can pass an input object that becomes available inside the task function as vars.input. This lets you provide all the context the task needs to do its work.

// Endpoint function - trigger the task with input data
// Run Task: "Send Welcome Email"
// Input: { email: input.email, name: input.name }

// Inside the background task function:
// vars.input.email → "[email protected]"
// vars.input.name  → "Jane Smith"

The input data is serialized when the task is queued, so it must be JSON-serializable. Database connections, file handles, and other non-serializable values cannot be passed to background tasks.

Task Configuration

Example: Bulk Email Campaign

An endpoint that accepts a list of recipients and sends emails in the background:

// POST /api/campaigns/send

// Step 1: Database Query - Get campaign details
// SELECT * FROM campaigns WHERE id = input.campaignId

// Step 2: Run Task - "Send Campaign Emails"
// Input: { campaignId: vars.campaign.id, recipients: input.recipients }

// Step 3: Update campaign status
// UPDATE campaigns SET status = 'sending' WHERE id = input.campaignId

// Step 4: Respond
// { status: "sending", recipientCount: input.recipients.length }

The background task function:

// Background Task: "Send Campaign Emails"

// Step 1: Database Query - Get campaign content
// SELECT * FROM campaigns WHERE id = input.campaignId

// Step 2: Loop - For each recipient
//   Step 3: Send Email (addon step)
//   to: recipient.email, subject: campaign.subject, body: campaign.html

// Step 4: Update campaign status
// UPDATE campaigns SET status = 'sent', sent_at = NOW()
// WHERE id = input.campaignId

Example: Image Processing Pipeline

Process an uploaded image through multiple transformations without blocking the upload response:

// POST /api/images/upload

// Step 1: Save original file to storage
// Step 2: Run Task - "Process Image"
//   Input: { imageId: vars.savedImage.id, path: vars.savedImage.path }
// Step 3: Respond with 202 Accepted

Background tasks run in a separate execution context. They do not have access to the original request headers, cookies, or authentication context. Pass any required data explicitly through the task input.

Monitoring Background Tasks

The Background Tasks monitor shows the status of all background task executions:

- Queued — Waiting to start
- Running — Currently executing
- Completed — Finished successfully
- Failed — Terminated with an error (check logs for details)
- Stopped — Manually stopped before completion
- Timed Out — Exceeded the configured timeout

Each execution record includes the input data, start/end times, duration, and any error output, giving you full visibility into what happened during each run.

From the monitor you can:

- Filter by status or addon
- Track running jobs against max concurrency
- Refresh job state
- Stop a running task when it is no longer needed
- Retry failed work after fixing configuration or data
- Open a detail view with prompt, result, and logs

A descriptive name for the task
Maximum execution time in seconds (default: 300)
Automatically retry if the task fails
Maximum retry attempts before marking as failed (default: 3)
Seconds to wait between retry attempts (default: 10)
Scheduled Tasks
/tasks/scheduled-tasks
Run functions on a repeat schedule or manually
Tasks Overview
/tasks
Learn about all task types in Spala