Introduction

emit.run is a background job processing system with reliable, stateful job execution — built-in retries, timeouts, and real-time progress tracking.

Core Concepts

Spaces

Jobs are organized into spaces. A space belongs to an organization and acts as an isolated queue — it has its own jobs, API tokens, and WebSocket event stream.

Common patterns:

• One space per environment: production, staging
• One space per job type: emails, video-processing, exports
• One space per team or customer

Jobs

A job represents a unit of work. Each job has:

Job Lifecycle

1. Created — Job enters pending state and is queued in the space's dispatch queue. If scheduledFor is set, the job enters scheduled state instead and waits until the specified time.
2. Scheduled (optional) — Job waits until scheduledFor time, then automatically transitions to pending and enters the dispatch queue.
3. Delivered — Worker polls and receives the job; status moves to delivered and a delivery timeout starts. If the worker never acks, the job reverts to pending automatically.
4. Running — Worker calls ack; status moves to running and the execution timeout starts
5. In progress — Worker sends strict progress updates (percent + user-facing message), checkpoint events, and optional custom events
6. Completed, Dead, or Killed — Worker calls complete (→ completed) or fail. On fail: retries remaining → re-queued as pending; no retries remaining → dead. An operator or control plane can call kill at any point before completion to force-stop the job as killed.
7. Callback — If callbackUrl was set, the system POSTs the result to that URL on completed, dead, or killed

Worker Flow

Workers are simple HTTP clients that poll for work:

Scopes

API keys use granular scopes so you can give each client exactly the permissions it needs.

Granular scopes:

Shorthand scopes (expand to multiple granular scopes):

Typical token setups: