Spaces

A space is a named set of jobs in your cluster, with its own settings. Use one per area of your product, like emails, billing or imports, so each can have its own retry policy, its own limits and its own tokens.

Every job lives in exactly one space, and the space is part of every job's address: /v1/spaces/emails/jobs/{id}. An SDK client works in one space, which you name when you create it.

Creating a space

You don't have to. A space is created by its first job, with the default settings. To choose its settings first, set it up on the cluster's Spaces tab in the dashboard, or configure it through the API before you send any jobs.

A space's name is up to 256 characters, with no /, and can't start with _emit.. Spaces can't be deleted, but an empty space costs nothing.

Settings

A job takes its space's defaults unless it says otherwise when it's created.

A cluster splits each space's jobs over a few shards so it can use all its machines. The in-flight limit and claims per minute are applied on each shard separately, so the space's total can be a few times the number you set. Use them as a brake on runaway load, not an exact count.

Changes to retries and timeouts apply to jobs created after the change. Everything else applies at once.

Changing settings

In the dashboard, open the space from the cluster's Spaces tab and choose Space settings. Through an SDK or the API, a token with the admin scope sends the whole set of settings. A setting you leave out goes back to its default, except the webhook secret, the retry growth and the unclaimed window, which stay as they are. To change one setting, read the space first and send it back changed:

const { admin } = new Emit({ url: process.env.EMIT_URL!, token: process.env.EMIT_ADMIN_TOKEN!, space: null });

const { name, ...settings } = await admin.spaces.get("emails");
await admin.spaces.configure("emails", { ...settings, defaultMaxAttempts: 8 });

admin := emit.New(emit.Options{URL: os.Getenv("EMIT_URL"), Token: os.Getenv("EMIT_ADMIN_TOKEN")}).Admin

space, err := admin.Spaces.Get(ctx, "emails")
if err != nil {
	return err
}
space.DefaultMaxAttempts = 8
if _, err := admin.Spaces.Configure(ctx, space); err != nil {
	return err
}

curl -s "$EMIT_URL/v1/spaces/emails" -H "Authorization: Bearer $EMIT_ADMIN_TOKEN" \
  | jq '.defaultMaxAttempts = 8' \
  | curl -s -X PUT "$EMIT_URL/v1/spaces/emails" \
  -H "Authorization: Bearer $EMIT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d @-

The Spaces API lists every field.

FIFO spaces

Without FIFO, workers get the oldest jobs first, but not in strict order: a space is spread over your whole cluster so it can use all of it, and jobs created close together may be handed out in a slightly different order.

A FIFO space hands jobs out strictly in the order they were created. A job that's delayed, or waiting to be retried, takes its place in the order when its wait ends. The price is throughput: a FIFO space runs on a single shard, so it can't spread its work over the whole cluster.

FIFO is fixed when the space gets its first job. Turn it on before then, when you set the space up.

Wake-ups

A worker usually holds a connection open and waits for jobs. A serverless function can't. Give the space a wake URL, and emit POSTs to it when jobs are waiting that nobody has been woken for, and again every 30 seconds while they're still unclaimed. The body names the space and how many jobs of each name are waiting:

{ "event": "work.pending", "space": "emails", "names": { "send-welcome-email": 3 }, "claim": { "count": 3 }, "timestamp": 1790726272531 }

Your function then claims jobs and reports on them like any worker. A wake-up is signed like a callback, with the same Emit-Signature header. You can limit wake-ups to some job names, and set how many jobs one wake-up stands for.

Tokens and spaces

An API token can be limited to some spaces. A token for emails can't read or create jobs in billing. See Authentication.