Skip to content

One-Off Jobs

Use a one-off job when you need something to happen once at a specific time, not on a recurring cadence.

  • Delayed action: send a follow-up email in 2 hours
  • Scheduled event: expire a trial on a specific date
  • Deferred work: process an upload after a 30-second buffer
  • Immediate background task: offload work from the request path

If the task recurs, use a schedule instead.

The CLI examples need the chronos CLI and either your key in CHRONOS_API_KEY or a login saved by chronos auth login.

The Node.js examples use a client from the Node.js SDK (0.2.0 or later):

import { Chronos } from '@chronos.sh/sdk';
const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });

The Go examples use a client from the Go SDK (Go 1.26 or later), inside a function that returns an error. They also use the standard library’s context, errors, fmt, os and time packages:

import chronos "chronos.sh/go"
client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))
if err != nil {
return err
}
ctx := context.Background()

Omit both delay and scheduled_for. The job runs as soon as possible:

Terminal window
chronos jobs create --name 'Process upload' --handler process-upload \
--payload '{"fileId":"file_abc123"}'

Use delay to run after a duration from now:

Terminal window
chronos jobs create --name 'Send follow-up' --handler send-email --delay 2h \
--payload '{"userId":"usr_123","template":"follow-up"}'

Available units: second, minute, hour, day, week. In the CLI, the units are s, m, h, d and w, as in 2h.

Use scheduled_for to run at a specific moment:

Terminal window
chronos jobs create --name 'Expire trial' --handler expire-trial \
--scheduled-for 2027-02-15T00:00:00Z \
--payload '{"accountId":"acc_456"}'

The time must be in the future (ISO 8601 format).

Prevent duplicate jobs with idempotency_key:

Terminal window
chronos jobs create --name 'Charge invoice inv_789' --handler charge-invoice --delay 1h \
--idempotency-key charge-inv_789 \
--payload '{"invoiceId":"inv_789"}'

If a job with the same idempotency_key already exists in your workspace, the API returns 409 with code idempotency_key_conflict instead of creating a duplicate. The CLI exits 5 with that error.code. The Node.js SDK throws it as a ChronosApiError, and the Go SDK returns it as an *APIError.

Use this when the trigger for job creation might fire multiple times (webhook retries, user double-clicks, distributed systems with at-least-once delivery).

The key is scoped to your workspace and persists for the lifetime of the job. Max 255 characters.

One-off jobs support the same delivery configuration as schedules:

Terminal window
chronos jobs create --name 'Send webhook notification' --handler notify --delay 5m \
--push-url https://your-app.com/hooks/chronos \
--payload '{"event":"subscription.created","data":{"id":"sub_123"}}'

If delivery is omitted, pull is the default. Your worker picks it up.

Override defaults per job. The same fields work in chronos.jobs.create, as Timeout and MaxRetries in JobCreateParams, and as --timeout 60s and --max-retries 5 in the CLI:

{
"name": "Critical charge",
"handler": "charge-invoice",
"delay": { "value": 1, "unit": "hour" },
"timeout": 60,
"max_retries": 5,
"payload": { "invoiceId": "inv_789" }
}
Field Default Description
timeout 30 Seconds before execution is considered timed out
max_retries 3 Number of retry attempts on failure. 0 = no retries.

To list only one-off jobs, filter by origin=api. Each example returns the first page, newest first:

Terminal window
chronos jobs list --origin api