Open source · Apache-2.0 Open source · Apache-2.0 · Postgres-backed

Job queue + workflow control plane

Queue the work.
Keep your code.

A PostgreSQL-backed queue that persists, claims, retries, and observes background work. Your workers stay in your environment and execute the business logic.

Spooled Queue state persist · claim · retry

Your worker Business logic execute · side effects

Try hosted free Self-hosting guide Source on GitHub

● PostgreSQL durability
● Retry + DLQ
● SSE + WebSocket

spooled ▸ illustrative workspace Demo

Enqueued

1,204

Running

Completed

998,320

Dead-letter

Queue activity illustrative

Recent jobs demo data

job_a7f2 stripe.invoice.paid running

job_a7f1 email.send done

job_a7f0 image.resize retry 2/5

job_a7ef webhook.deliver done

Quickstart

Up and running in minutes

Enqueue over the API, run a worker in your environment, then subscribe to state changes. Official SDKs cover Node.js, Python, Go, and PHP.

Enqueue a job

POST a queue name and JSON payload. Pass an idempotency key and duplicate submissions collapse into one job. Bulk enqueue accepts up to 100 jobs per request.

Jobs & queues docs →

curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "my-queue",
    "payload": {
      "event": "user.created",
      "user_id": "usr_123",
      "email": "alice@example.com"
    },
    "idempotency_key": "user-created-usr_123"
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const userId = 'usr_123';

// Create a job
const { id } = await client.jobs.create({
  queueName: 'email-notifications',
  payload: {
    to: 'user@example.com',
    subject: 'Welcome!',
    template: 'welcome',
  },
  idempotencyKey: `welcome-${userId}`,
  maxRetries: 5,
});

console.log(`Created job: ${id}`);

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

image_id = "img_123"

# Create a background job
result = client.jobs.create({
    "queue_name": "image-processing",
    "payload": {
        "image_url": "https://example.com/image.jpg",
        "operations": ["resize", "compress"],
        "output_format": "webp"
    },
    "idempotency_key": f"process-image-{image_id}",
    "max_retries": 3
})

print(f"Created job: {result.id}")

client.close()

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	resp, err := client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
		QueueName:      "my-queue",
		Payload:        map[string]any{"key": "value"},
		IdempotencyKey: ptr("unique-key"),
		MaxRetries:     ptr(3),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Created job: %s\n", resp.ID)
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$userId = 'usr_123';

// Create a job
$job = $client->jobs->create([
    'queue' => 'email-notifications',
    'payload' => [
        'to' => 'user@example.com',
        'subject' => 'Welcome!',
        'template' => 'welcome',
    ],
    'idempotencyKey' => "welcome-{$userId}",
    'maxRetries' => 5,
]);

echo "Created job: {$job->id}\n";

Run a worker

Workers run on your infrastructure. They claim jobs, run your code, and report complete or fail. Failures retry with exponential backoff — up to 100 attempts — then land in the dead-letter queue.

Worker docs →

# Worker loop: claim → process → complete/fail
# 1. Claim jobs
curl -X POST https://api.spooled.cloud/api/v1/jobs/claim \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"queue_name": "my-queue", "worker_id": "worker-1", "limit": 5}'

# 2. Complete a job
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz/complete \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"worker_id": "worker-1"}'

# 3. Or fail it (will retry)
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz/fail \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"worker_id": "worker-1", "error": "Processing failed"}'

import { SpooledClient, SpooledWorker } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const worker = new SpooledWorker(client, {
  queueName: 'email-notifications',
  concurrency: 10,
});

worker.process(async (ctx) => {
  const { to, subject, body } = ctx.payload;
  await sendEmail({ to, subject, body });
  console.log(`Sent email to ${to}`);
  return { sent: true };
});

await worker.start();

from spooled import SpooledClient
from spooled.worker import SpooledWorker
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])
worker = SpooledWorker(client, queue_name="email-notifications", concurrency=10)

@worker.process
def handle_job(ctx):
    to = ctx.payload["to"]
    subject = ctx.payload["subject"]
    
    # Process the job
    send_email(to, subject)
    
    return {"sent": True}

worker.start()  # Blocking

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/worker"
)

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	w := worker.NewWorker(client.Jobs(), client.Workers(), worker.Options{
		QueueName:   "email-notifications",
		Concurrency: 10,
	})

	w.Process(func(ctx *worker.JobContext) (map[string]any, error) {
		fmt.Printf("Job %s payload=%v\n", ctx.JobID, ctx.Payload)
		return map[string]any{"ok": true}, nil
	})

	if err := w.Start(context.Background()); err != nil {
		panic(err)
	}
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;
use Spooled\Worker\SpooledWorker;
use Spooled\Worker\WorkerConfig;
use Spooled\Worker\JobContext;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$worker = new SpooledWorker($client, new WorkerConfig(
    queueName: 'email-notifications',
    concurrency: 10,
));

$worker->process(function (JobContext $ctx): array {
    $to = $ctx->get('to');
    $subject = $ctx->get('subject');
    
    // Process the job
    sendEmail($to, $subject);
    
    return ['sent' => true];
});

$worker->start();

Stream the results

Subscribe over Server-Sent Events or WebSocket instead of polling. The dashboard shows throughput, latency, failures, and DLQ replays from the same streams.

Real-time API docs →

# Stream events via Server-Sent Events
curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  "https://api.spooled.cloud/api/v1/events"

# Stream events for a specific queue
curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  "https://api.spooled.cloud/api/v1/events/queues/my-queue"

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// SSE realtime client (uses /api/v1/events with Authorization header under the hood)
const realtime = await client.realtime({ type: 'sse' });

realtime.on('job.created', (data) => {
  console.log('job.created:', data);
});

await realtime.connect();
await realtime.subscribe({ queueName: 'orders' });

from spooled import SpooledClient
from spooled.realtime import SubscriptionFilter
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

realtime = client.realtime(type="sse")

@realtime.on("job.created")
def on_job_created(data):
    print("job.created:", data)

realtime.connect()
realtime.subscribe(SubscriptionFilter(queue="orders"))

import (
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/realtime"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

sse := client.Realtime().SSE()

sse.OnEvent("job.created", func(data realtime.EventData) {
	fmt.Println("job.created:", data)
})

sse.Connect(context.Background())
sse.Subscribe(realtime.Filter{QueueName: "orders"})

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// SSE realtime client
$realtime = $client->realtime();

$realtime->sse()->subscribe(function (array $event): void {
    echo "Event: {$event['type']} - Job: {$event['data']['jobId']}\n";
});

$realtime->sse()->subscribeToQueue('orders', function (array $event): void {
    echo "Queue event: {$event['type']}\n";
});

$realtime->sse()->listen();

Real-time

See your queues live

The hosted dashboard subscribes to the very streams you saw fan out above — so what you watch here is exactly what your own clients receive, with no polling.

In the dashboard

Job timeline Follow a job through retries to its outcome.

Dead-letter replay Inspect failures and replay once fixed.

Queue stats Throughput, pending counts, and latency at a glance.

Worker health Active workers, leases, and heartbeats in real time.

Open the dashboard →

Same streams, your clients

Server-Sent Events One-way stream for dashboards and live views. Reconnects on its own.
WebSocket Two-way channel when you need to send filters and commands back.

See the subscribe code ↑

Live demo

Watch jobs flow through the queue

Spooled stores every job in Postgres. Your workers claim and process them in parallel, failures auto-retry, and state changes stream to dashboards and clients. This simulation shows the lifecycle without pretending to be production telemetry.

Pipeline preview

Demo

Incoming 2 queued

job_128 pending

stripe.invoice.paid

job_129 pending

user.signup

Processing 2 active

job_126 processing

github.push

job_127 processing

order.created

Completed 2 done

job_124 completed

email.send

job_125 completed

webhook.deliver

Illustrative states. Pro API allowance: 100 requests/sec (burst 200); completed and failed records are retained for 30 days.

Official SDKs: Node.js · Python · Go · PHP

Other marks show compatible HTTP sources and infrastructure, not native integrations.

Stripe
GitHub
Shopify
PostgreSQL
Redis
Node.js
Python
Go
PHP

Reliability

The safety net around every job

Failed jobs retry with exponential backoff. Exhausted jobs move to the dead-letter queue with payload and error history preserved. This shortened simulation shows inspect, fix, and replay; production jobs can be configured for up to 100 attempts.

job a1f9c… · queue payment-processing

Ready — press play to run the retry flow.

Initial attempt
t = 0s

Worker claims the job and runs it

Failed · HTTP 500
1

Retry #1
t + 1m

First backoff delay — 1 minute

Failed · Timeout
2

Retry #2
t + 3m

Delay doubles — 2 minutes

Failed · Connection refused
3

Retry #3
t + 7m

Delay doubles again — 4 minutes

Failed · HTTP 503
Dead-letter queue
exhausted

Payload and error history preserved for inspect & replay

Parked · inspect & replay

Backoff schedule

1m try 1

2m try 2

4m try 3

8m try 4

16m try 5

32m try 6

60m try 7+

Backoff formula


delay_minutes = min(2 ** retry_count, 60)

Retries are scheduled in minutes (1m, 2m, 4m …), doubling each time and capped at 60m, for up to 100 attempts. Exhausted jobs land in the dead-letter queue with their payload and error history intact — inspect and replay them from the dashboard or the API.

Recovery procedure

Inspect, fix, replay

DLQ API reference →

Exhausted jobs keep their payload and error history. Recovery is explicit rather than silently dropping or endlessly cycling bad work.

01 / INSPECTRead payload + error historyIdentify whether failure came from data, code, or a dependency.
02 / FIXCorrect the underlying causeDeploy the worker fix or restore the unavailable service.
03 / REPLAYRetry one or many jobsReplay through the API or dashboard with traceability intact.

Declare which jobs depend on which, and Spooled runs the graph for you. Roots go first, independent branches run in parallel, and a failed parent cancels everything downstream.

Workflow run

Live

completed

create-account

queue: users

completed

send-welcome-email

queue: emails

completed

setup-defaults

queue: users

waiting running completed

3 / 3 done

The workflow behind it

# Create a workflow with job dependencies
curl -X POST https://api.spooled.cloud/api/v1/workflows \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-onboarding",
    "jobs": [
      {
        "key": "create-account",
        "queue_name": "users",
        "payload": {"email": "user@example.com", "plan": "pro"}
      },
      {
        "key": "send-welcome-email",
        "queue_name": "emails",
        "depends_on": ["create-account"],
        "payload": {"template": "welcome"}
      },
      {
        "key": "setup-defaults",
        "queue_name": "users",
        "depends_on": ["create-account"],
        "payload": {"settings": {}}
      }
    ]
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// Create a workflow with job dependencies
const workflow = await client.workflows.create({
  name: 'user-onboarding',
  jobs: [
    {
      key: 'create-account',
      queueName: 'users',
      payload: { email: 'user@example.com', plan: 'pro' },
    },
    {
      key: 'send-welcome-email',
      queueName: 'emails',
      dependsOn: ['create-account'],  // Waits for this job
      payload: { template: 'welcome' },
    },
    {
      key: 'setup-defaults',
      queueName: 'users',
      dependsOn: ['create-account'],  // Also waits
      payload: { settings: {} },
    },
  ],
});

console.log(`Created workflow: ${workflow.workflowId}`);

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

# Create a workflow with job dependencies
workflow = client.workflows.create({
    "name": "user-onboarding",
    "jobs": [
        {
            "key": "create-account",
            "queue_name": "users",
            "payload": {"email": "user@example.com", "plan": "pro"}
        },
        {
            "key": "send-welcome-email",
            "queue_name": "emails",
            "depends_on": ["create-account"],  # Waits for this job
            "payload": {"template": "welcome"}
        },
        {
            "key": "setup-defaults",
            "queue_name": "users",
            "depends_on": ["create-account"],  # Also waits
            "payload": {"settings": {}}
        }
    ]
})

print(f"Created workflow: {workflow.workflow_id}")

import (
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

client := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

resp, err := client.Workflows().Create(context.Background(), &resources.CreateWorkflowRequest{
	Name: "user-onboarding",
	Jobs: []resources.WorkflowJobDefinition{
		{
			Key:       "create-account",
			QueueName: "users",
			Payload:   map[string]interface{}{"email": "user@example.com", "plan": "pro"},
		},
		{
			Key:       "send-welcome-email",
			QueueName: "emails",
			Payload:   map[string]interface{}{"template": "welcome"},
			DependsOn: []string{"create-account"},
		},
		{
			Key:       "setup-defaults",
			QueueName: "users",
			Payload:   map[string]interface{}{"settings": map[string]interface{}{}},
			DependsOn: []string{"create-account"},
		},
	},
})
if err != nil {
	panic(err)
}

fmt.Printf("Created workflow: %s\n", resp.WorkflowID)

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// Create a workflow with job dependencies
$workflow = $client->workflows->create([
    'name' => 'user-onboarding',
    'jobs' => [
        [
            'key' => 'create-account',
            'queue' => 'users',
            'payload' => ['email' => 'user@example.com', 'plan' => 'pro'],
        ],
        [
            'key' => 'send-welcome-email',
            'queue' => 'emails',
            'dependsOn' => ['create-account'], // Waits for this job
            'payload' => ['template' => 'welcome'],
        ],
        [
            'key' => 'setup-defaults',
            'queue' => 'users',
            'dependsOn' => ['create-account'], // Also waits
            'payload' => ['settings' => []],
        ],
    ],
]);

echo "Created workflow: {$workflow->workflowId}\n";

Illustrative motion. Workflows are a paid feature — Pro runs up to 25 concurrent workflows; the Free tier does not include them.

Give a job a priority and workers claim the highest first — high (10) before normal (0) before low (-10). Same enqueue call, one extra field.

Waiting to be claimed

6 jobs

VIP order High · +10
Pager alert High · +10
Send receipt Normal · 0
Send invite Normal · 0
Nightly cleanup Low · -10
Rebuild report Low · -10

worker · claiming

Processed in order

0 done

VIP order #1
Pager alert #2
Send receipt #3
Send invite #4
Nightly cleanup #5
Rebuild report #6

Priority only orders the claim — every job still runs. On the Free plan up to 10 jobs run at once, so higher priority simply gets there first.

The one extra field

# High priority - processed first (VIP customer order)
curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "orders",
    "payload": {"order_id": 789, "customer_tier": "vip"},
    "priority": 10
  }'

# Normal priority (default: 0)
# Low priority: -10 (background cleanup)
# Workers claim jobs: High → Normal → Low

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// High priority - VIP customer order (processed first)
await client.jobs.create({
  queueName: 'orders',
  payload: { orderId: 789, customerTier: 'vip' },
  priority: 10,  // High priority
});

// Normal priority (default)
await client.jobs.create({
  queueName: 'orders',
  payload: { orderId: 790 },
  priority: 0,   // Default
});

// Low priority - background cleanup
await client.jobs.create({
  queueName: 'maintenance',
  payload: { task: 'cleanup' },
  priority: -10, // Low priority
});

// Workers claim jobs: High → Normal → Low

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

# High priority - VIP customer order (processed first)
client.jobs.create({
    "queue_name": "orders",
    "payload": {"order_id": 789, "customer_tier": "vip"},
    "priority": 10   # High priority
})

# Normal priority (default)
client.jobs.create({
    "queue_name": "orders",
    "payload": {"order_id": 790},
    "priority": 0    # Default
})

# Low priority - background cleanup
client.jobs.create({
    "queue_name": "maintenance",
    "payload": {"task": "cleanup"},
    "priority": -10  # Low priority
})

# Workers claim jobs: High → Normal → Low

import (
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

// High priority - VIP customer order (processed first)
client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
	QueueName: "orders",
	Payload:   map[string]interface{}{"order_id": 789, "customer_tier": "vip"},
	Priority:  intPtr(10), // High priority
})

// Normal priority (default)
client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
	QueueName: "orders",
	Payload:   map[string]interface{}{"order_id": 790},
	Priority:  intPtr(0), // Default
})

// Low priority - background cleanup
client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
	QueueName: "maintenance",
	Payload:   map[string]interface{}{"task": "cleanup"},
	Priority:  intPtr(-10), // Low priority
})

// Workers claim jobs: High → Normal → Low

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// High priority - VIP customer order (processed first)
$client->jobs->create([
    'queue' => 'orders',
    'payload' => ['orderId' => 789, 'customerTier' => 'vip'],
    'priority' => 10, // High priority
]);

// Normal priority (default)
$client->jobs->create([
    'queue' => 'orders',
    'payload' => ['orderId' => 790],
    'priority' => 0, // Default
]);

// Low priority - background cleanup
$client->jobs->create([
    'queue' => 'maintenance',
    'payload' => ['task' => 'cleanup'],
    'priority' => -10, // Low priority
]);

// Workers claim jobs: High → Normal → Low

Describe when with a 6-field cron expression and Spooled enqueues the job for you, second-precise and timezone-aware. Pick a pattern and watch the next runs fill in.

Pick a schedule

Cron expression Morning report

0 sec

0 min

9 hour

* day

* month

* wday

Six fields: second, minute, hour, day-of-month, month, day-of-week.

Next runs

Computed

1

Tomorrow, 9:00 AM

in 6 hours
2

Fri, 9:00 AM

in 1 day
3

Sat, 9:00 AM

in 2 days
4

Sun, 9:00 AM

in 3 days

Preview computed in your browser. Free includes 1 schedule, Pro allows 50 with 30-day job history.

The call that creates the schedule

# Create a cron schedule
curl -X POST https://api.spooled.cloud/api/v1/schedules \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Report",
    "cron_expression": "0 0 9 * * *",
    "timezone": "America/New_York",
    "queue_name": "reports",
    "payload_template": {"type": "daily_report"}
  }'

// Create a cron schedule
const schedule = await client.schedules.create({
  name: 'Daily Report',
  cronExpression: '0 0 9 * * *',
  timezone: 'America/New_York',
  queueName: 'reports',
  payloadTemplate: { type: 'daily_report' },
});

# Create a cron schedule
schedule = client.schedules.create({
    "name": "Daily Report",
    "cron_expression": "0 0 9 * * *",
    "timezone": "America/New_York",
    "queue_name": "reports",
    "payload_template": {"type": "daily_report"}
})

import (
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

client, err := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))
if err != nil {
	panic(err)
}

schedule, err := client.Schedules().Create(context.Background(), &resources.CreateScheduleRequest{
	Name:            "Daily Report",
	CronExpression:  "0 0 9 * * *",
	Timezone:        ptr("America/New_York"),
	QueueName:       "reports",
	PayloadTemplate: map[string]interface{}{"type": "daily_report"},
})
if err != nil {
	panic(err)
}

fmt.Printf("Created schedule: %s\n", schedule.ID)

<?php

// Create a cron schedule
$schedule = $client->schedules->create([
    'name' => 'Daily Report',
    'cronExpression' => '0 0 9 * * *',
    'timezone' => 'America/New_York',
    'queue' => 'reports',
    'payloadTemplate' => ['type' => 'daily_report'],
]);

echo "Created schedule: {$schedule->id}\n";

Throughput

Keep workers fed without polling

gRPC bidirectional streaming keeps a worker and Spooled talking over one open HTTP/2 connection, so a single worker can process thousands of jobs per second — no per-job round trip, no polling.

In practice

See it in real code

Three patterns you can copy today. Each pairs the enqueue side with the worker side — the same durable queue sits between them. Pick a scenario, then expand any block to read the full snippet.

Live proof · SpriteForge ↗

One sprite is one workflow.

Frame generation fans out as parallel jobs. The assemble job waits on every frame, then the result streams back to the client.

prompt
workflow
frames 1..N
parallel
dependency
join
assemble
result

Reliable Stripe checkout

Ack the Stripe webhook in milliseconds, then let a durable job fulfil the order — retried automatically if fulfilment fails.

Receive the event

Verify the signature, enqueue a job, return 200 fast.

# Queue a Stripe webhook event
curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "stripe-events",
    "payload": {
      "id": "evt_1234",
      "type": "invoice.paid",
      "data": {"object": {...}}
    },
    "idempotency_key": "evt_1234"
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// Express.js webhook handler
app.post('/webhooks/stripe', async (req, res) => {
  const sig = req.headers['stripe-signature'];
  
  try {
    // Verify and parse the webhook
    const event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
    
    // Queue in Spooled for reliable processing
    await client.jobs.create({
      queueName: 'stripe-events',
      payload: event,
      idempotencyKey: event.id,
    });
    
    // Return 200 immediately - Spooled handles retries
    res.status(200).send('Queued');
  } catch (error) {
    res.status(400).send(`Webhook Error: ${error.message}`);
  }
});

from flask import Flask, request
from spooled import SpooledClient
import stripe
import os

app = Flask(__name__)
client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

@app.route('/webhooks/stripe', methods=['POST'])
def handle_stripe_webhook():
    payload = request.data
    sig = request.headers.get('Stripe-Signature')
    
    try:
        event = stripe.Webhook.construct_event(
            payload, sig, os.environ['STRIPE_WEBHOOK_SECRET']
        )
        
        # Queue in Spooled for reliable processing
        client.jobs.create({
            "queue_name": "stripe-events",
            "payload": event,
            "idempotency_key": event['id']
        })
        
        return 'Queued', 200
    except Exception as e:
        return f'Webhook Error: {str(e)}', 400

import (
	"context"
	"net/http"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

// HTTP handler for Stripe webhooks
http.HandleFunc("/webhooks/stripe", func(w http.ResponseWriter, r *http.Request) {
	event, _ := stripe.ConstructEvent(r.Body, r.Header.Get("Stripe-Signature"), webhookSecret)
	
	// Queue in Spooled for reliable processing
	client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
		QueueName:      "stripe-events",
		Payload:        event,
		IdempotencyKey: stringPtr(event.ID),
	})
	
	w.WriteHeader(http.StatusOK)
})

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// Slim/Laravel webhook handler
$app->post('/webhooks/stripe', function ($request, $response) use ($client) {
    $sig = $request->getHeaderLine('Stripe-Signature');
    $payload = (string) $request->getBody();
    
    $event = \Stripe\Webhook::constructEvent(
        $payload, $sig, getenv('STRIPE_WEBHOOK_SECRET')
    );
    
    // Queue in Spooled for reliable processing
    $client->jobs->create([
        'queue' => 'stripe-events',
        'payload' => $event->toArray(),
        'idempotencyKey' => $event->id,
    ]);
    
    return $response->withStatus(200);
});

Fulfil in a worker

Claim → do the work → complete or fail, on your own servers.

# Worker loop: claim → process → complete/fail
# 1. Claim jobs
curl -X POST https://api.spooled.cloud/api/v1/jobs/claim \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"queue_name": "my-queue", "worker_id": "worker-1", "limit": 5}'

# 2. Complete a job
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz/complete \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"worker_id": "worker-1"}'

# 3. Or fail it (will retry)
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz/fail \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"worker_id": "worker-1", "error": "Processing failed"}'

import { SpooledClient, SpooledWorker } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const worker = new SpooledWorker(client, {
  queueName: 'email-notifications',
  concurrency: 10,
});

worker.process(async (ctx) => {
  const { to, subject, body } = ctx.payload;
  await sendEmail({ to, subject, body });
  console.log(`Sent email to ${to}`);
  return { sent: true };
});

await worker.start();

from spooled import SpooledClient
from spooled.worker import SpooledWorker
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])
worker = SpooledWorker(client, queue_name="email-notifications", concurrency=10)

@worker.process
def handle_job(ctx):
    to = ctx.payload["to"]
    subject = ctx.payload["subject"]
    
    # Process the job
    send_email(to, subject)
    
    return {"sent": True}

worker.start()  # Blocking

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/worker"
)

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	w := worker.NewWorker(client.Jobs(), client.Workers(), worker.Options{
		QueueName:   "email-notifications",
		Concurrency: 10,
	})

	w.Process(func(ctx *worker.JobContext) (map[string]any, error) {
		fmt.Printf("Job %s payload=%v\n", ctx.JobID, ctx.Payload)
		return map[string]any{"ok": true}, nil
	})

	if err := w.Start(context.Background()); err != nil {
		panic(err)
	}
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;
use Spooled\Worker\SpooledWorker;
use Spooled\Worker\WorkerConfig;
use Spooled\Worker\JobContext;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$worker = new SpooledWorker($client, new WorkerConfig(
    queueName: 'email-notifications',
    concurrency: 10,
));

$worker->process(function (JobContext $ctx): array {
    $to = $ctx->get('to');
    $subject = $ctx->get('subject');
    
    // Process the job
    sendEmail($to, $subject);
    
    return ['sent' => true];
});

$worker->start();

Fan out a batch import

Turn one CSV upload into thousands of independent jobs — each row gets its own retry, idempotency key, and worker.

Enqueue per row

Read the file once, enqueue one job for every record.

import { SpooledClient } from '@spooled/sdk';
import fs from 'node:fs/promises';

const client = new SpooledClient({ apiKey: process.env.SPOOLED_API_KEY! });

const csv = await fs.readFile('users.csv', 'utf8');
const [headerLine, ...rows] = csv.trim().split(/\r?\n/);
const headers = headerLine.split(',').map((s) => s.trim());

for (const row of rows) {
  if (!row.trim()) continue;
  const values = row.split(',').map((s) => s.trim());
  const payload: Record<string, string> = {};
  headers.forEach((h, i) => (payload[h] = values[i] ?? ''));

  await client.jobs.create({
    queueName: 'csv-import',
    payload,
    idempotencyKey: payload.email ? `csv-${payload.email}` : undefined,
  });
}

console.log('✅ Enqueued CSV jobs');

import csv
import os
from spooled import SpooledClient

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

with open("users.csv", newline="") as f:
    reader = csv.DictReader(f)
    for row in reader:
        email = row.get("email") or ""
        client.jobs.create({
            "queue_name": "csv-import",
            "payload": row,
            "idempotency_key": f"csv-{email}" if email else None,
        })

print("✅ Enqueued CSV jobs")
client.close()

package main

import (
	"context"
	"encoding/csv"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	f, err := os.Open("users.csv")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	r := csv.NewReader(f)
	records, err := r.ReadAll()
	if err != nil {
		panic(err)
	}
	if len(records) < 2 {
		return
	}

	headers := records[0]
	for _, rec := range records[1:] {
		payload := map[string]any{}
		for i, h := range headers {
			if i < len(rec) {
				payload[h] = rec[i]
			}
		}

		var idem *string
		if email, ok := payload["email"].(string); ok && email != "" {
			idem = ptr("csv-" + email)
		}

		_, err := client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
			QueueName:      "csv-import",
			Payload:        payload,
			IdempotencyKey: idem,
		})
		if err != nil {
			panic(err)
		}
	}
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$fh = fopen('users.csv', 'r');
$headers = fgetcsv($fh);

while (($row = fgetcsv($fh)) !== false) {
    $payload = array_combine($headers, $row);
    $email = $payload['email'] ?? null;

    $client->jobs->create([
        'queue' => 'csv-import',
        'payload' => $payload,
        'idempotencyKey' => $email ? "csv-{$email}" : null,
    ]);
}

fclose($fh);
echo "✅ Enqueued CSV jobs\n";

Process each job

A minimal worker — swap the body for your real work.

import { SpooledClient, SpooledWorker } from '@spooled/sdk';

const client = new SpooledClient({ apiKey: process.env.SPOOLED_API_KEY! });

const worker = new SpooledWorker(client, {
  queueName: 'my-queue',
  concurrency: 1,
});

worker.process(async (ctx) => {
  console.log('Job ID:', ctx.jobId);
  console.log('Payload:', ctx.payload);
  return { ok: true };
});

await worker.start();

from spooled import SpooledClient
from spooled.worker import SpooledWorker
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])
worker = SpooledWorker(client, queue_name="my-queue", concurrency=1)

@worker.process
def handle_job(ctx):
    print("Job ID:", ctx.job_id)
    print("Payload:", ctx.payload)
    return {"ok": True}

worker.start()  # Blocking

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/worker"
)

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	w := worker.NewWorker(client.Jobs(), client.Workers(), worker.Options{
		QueueName:   "my-queue",
		Concurrency: 1,
	})

	w.Process(func(ctx *worker.JobContext) (map[string]any, error) {
		fmt.Println("Job ID:", ctx.JobID)
		fmt.Println("Payload:", ctx.Payload)
		return map[string]any{"ok": true}, nil
	})

	if err := w.Start(context.Background()); err != nil {
		panic(err)
	}
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;
use Spooled\Worker\SpooledWorker;
use Spooled\Worker\WorkerConfig;
use Spooled\Worker\JobContext;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$worker = new SpooledWorker($client, new WorkerConfig(
    queueName: 'my-queue',
    concurrency: 1,
));

$worker->process(function (JobContext $ctx): array {
    echo "Job ID: {$ctx->jobId()}\n";
    print_r($ctx->payload());
    return ['ok' => true];
});

$worker->start();

Push-to-deploy webhooks

A GitHub push enqueues a deploy job; a worker runs build, test, and release with retries instead of a flaky inline script.

On every push

Take the GitHub payload and enqueue a deploy job.

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// GitHub webhook handler
app.post('/webhooks/github', async (req, res) => {
  const event = req.headers['x-github-event'];
  const delivery = req.headers['x-github-delivery'];
  
  // Queue for processing
  await client.jobs.create({
    queueName: 'github-events',
    payload: {
      event,
      data: req.body,
    },
    idempotencyKey: delivery, // Use delivery ID for deduplication
  });
  
  res.status(200).send('Queued');
});

from flask import Flask, request
from spooled import SpooledClient

app = Flask(__name__)
client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

@app.route('/webhooks/github', methods=['POST'])
def handle_github_webhook():
    event = request.headers.get('X-GitHub-Event')
    delivery = request.headers.get('X-GitHub-Delivery')
    
    # Queue for processing
    client.jobs.create({
        "queue_name": "github-events",
        "payload": {
            "event": event,
            "data": request.json
        },
        "idempotency_key": delivery  # Deduplication
    })
    
    return 'Queued', 200

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// Slim/Laravel webhook handler
$app->post('/webhooks/github', function ($request, $response) use ($client) {
    $event = $request->getHeaderLine('X-GitHub-Event');
    $delivery = $request->getHeaderLine('X-GitHub-Delivery');
    $payload = json_decode((string) $request->getBody(), true);
    
    // Queue for processing
    $client->jobs->create([
        'queue' => 'github-events',
        'payload' => [
            'event' => $event,
            'data' => $payload,
        ],
        'idempotencyKey' => $delivery, // Deduplication
    ]);
    
    return $response->withStatus(200);
});

Run the deploy

A worker claims the job and drives the pipeline.

# Worker loop: claim → process → complete/fail
# 1. Claim jobs
curl -X POST https://api.spooled.cloud/api/v1/jobs/claim \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"queue_name": "my-queue", "worker_id": "worker-1", "limit": 5}'

# 2. Complete a job
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz/complete \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"worker_id": "worker-1"}'

# 3. Or fail it (will retry)
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz/fail \
  -H "Authorization: Bearer sp_live_..." \
  -d '{"worker_id": "worker-1", "error": "Processing failed"}'

import { SpooledClient, SpooledWorker } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const worker = new SpooledWorker(client, {
  queueName: 'email-notifications',
  concurrency: 10,
});

worker.process(async (ctx) => {
  const { to, subject, body } = ctx.payload;
  await sendEmail({ to, subject, body });
  console.log(`Sent email to ${to}`);
  return { sent: true };
});

await worker.start();

from spooled import SpooledClient
from spooled.worker import SpooledWorker
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])
worker = SpooledWorker(client, queue_name="email-notifications", concurrency=10)

@worker.process
def handle_job(ctx):
    to = ctx.payload["to"]
    subject = ctx.payload["subject"]
    
    # Process the job
    send_email(to, subject)
    
    return {"sent": True}

worker.start()  # Blocking

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/worker"
)

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	w := worker.NewWorker(client.Jobs(), client.Workers(), worker.Options{
		QueueName:   "email-notifications",
		Concurrency: 10,
	})

	w.Process(func(ctx *worker.JobContext) (map[string]any, error) {
		fmt.Printf("Job %s payload=%v\n", ctx.JobID, ctx.Payload)
		return map[string]any{"ok": true}, nil
	})

	if err := w.Start(context.Background()); err != nil {
		panic(err)
	}
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;
use Spooled\Worker\SpooledWorker;
use Spooled\Worker\WorkerConfig;
use Spooled\Worker\JobContext;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$worker = new SpooledWorker($client, new WorkerConfig(
    queueName: 'email-notifications',
    concurrency: 10,
));

$worker->process(function (JobContext $ctx): array {
    $to = $ctx->get('to');
    $subject = $ctx->get('subject');
    
    // Process the job
    sendEmail($to, $subject);
    
    return ['sent' => true];
});

$worker->start();

How it fits

Division of labor

Spooled never runs your code. It stores jobs, schedules retries, and streams status; your workers do the work, wherever they already run.

Spooled handles

Durable job storage in Postgres
Retries with exponential backoff
Deduplication via idempotency keys
Dead-letter queues and replay
Schedules, workflows, priorities
Live status over SSE / WebSocket

You provide

Workers — your code, your servers
Email/SMS providers you already use
Storage (S3, R2, GCS…)
External APIs your jobs call
The business logic itself

Your workers stay on your infrastructure and keep your secrets — Spooled only sees the job payloads you send it.

Architecture

Rust core, Postgres durability, open end to end

The API and workers are Rust. PostgreSQL is the source of truth — every job, retry, and dead-letter entry is a row you could query, with every query scoped to your organization. Redis carries only real-time pub/sub for live dashboards and streams; losing it never loses a job.

The core is Apache-2.0: backend, queue engine, and all four SDKs. Self-host it against your own Postgres with no platform limits, or use the hosted cloud and skip the operating. Same API either way.

Source on GitHub → Architecture docs → Self-host guide →

100

jobs per bulk enqueue

6-field

cron, second precision

SSE + WS

real-time job streams

REST + gRPC

APIs, HTTP/2 streaming

How work flows through Spooled

claimed

completed

FAQ

Questions engineers ask

What is Spooled Cloud?

Spooled is an open-source job queue backed by PostgreSQL. You enqueue jobs over REST or gRPC; your workers claim and run them; Spooled stores every job durably, retries failures with exponential backoff, and moves exhausted jobs to a dead-letter queue. The core is Apache-2.0 and self-hostable, with a hosted cloud option.

Is Spooled a job queue without Redis?

Yes. Jobs are stored in PostgreSQL, so durability does not depend on Redis. Redis is used only for real-time pub/sub (live dashboards and WebSocket/SSE streams), not as the source of truth for job state.

How do retries and the dead-letter queue work?

Failed jobs retry automatically with exponential backoff. You configure max attempts (up to 100) and delays. Jobs that exhaust retries land in the dead-letter queue, where you can inspect payloads, bulk retry, or purge with filters.

What delivery semantics should I design for?

Workers claim jobs with leases. If a worker disappears before reporting completion, the lease expires and the job can be claimed again. Design side effects to be idempotent; enqueue idempotency keys prevent duplicate submissions, but they are not an exactly-once execution guarantee.

Where does my worker code run?

On your infrastructure. Workers are plain processes that claim jobs from Spooled, run your code, and report success or failure. Spooled never executes your code — it stores jobs, schedules retries, and streams status.

How are job payloads stored?

Job payloads are stored as plaintext JSONB in PostgreSQL. Use your database and infrastructure controls to protect access, and put sensitive or large objects in your own storage with a reference in the job payload.

Is Spooled open source? Can I self-host it?

The core — the Rust backend, queue engine, and all SDKs — is Apache-2.0 on GitHub. You can self-host it with your own PostgreSQL with no platform limits, or use the hosted cloud with a free tier of 1,000 jobs per day.

Get started

Put one real workload on a durable queue.

Try hosted Spooled with 1,000 jobs a day, or run the Apache-2.0 core against your own PostgreSQL.

Start free Self-host with Docker

No credit card required
Free tier forever
Open source — Apache-2.0

Queue the work.Keep your code.

Up and running in minutes

Enqueue a job

Run a worker

Stream the results

See your queues live

In the dashboard

Same streams, your clients

Watch jobs flow through the queue

Pipeline preview

The safety net around every job

job a1f9c… · queue payment-processing

Initial attempt

Retry #1

Retry #2

Retry #3

Dead-letter queue

Backoff schedule

Inspect, fix, replay

Order, priority, and timing

Workflow run

The workflow behind it

Waiting to be claimed

Processed in order

The one extra field

Pick a schedule

Next runs

The call that creates the schedule

Keep workers fed without polling

See it in real code

One sprite is one workflow.

Reliable Stripe checkout

Receive the event

Fulfil in a worker

Fan out a batch import

Enqueue per row

Process each job

Push-to-deploy webhooks

On every push

Run the deploy

Division of labor

Spooled handles

You provide

Rust core, Postgres durability, open end to end

How work flows through Spooled

Questions engineers ask

Put one real workload on a durable queue.

Queue the work.
Keep your code.