One-Off Jobs

When to use 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.

Timing options

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

curl -X POST https://api.chronos.sh/v1/jobs \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Process upload",
    "handler": "process-upload",
    "payload": { "fileId": "file_abc123" }
  }'

Use delay to run after a duration from now:

curl -X POST https://api.chronos.sh/v1/jobs \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Send follow-up",
    "handler": "send-email",
    "delay": { "value": 2, "unit": "hour" },
    "payload": { "userId": "usr_123", "template": "follow-up" }
  }'

Available units: second, minute, hour, day, week

Use scheduled_for to run at a specific moment:

curl -X POST https://api.chronos.sh/v1/jobs \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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).

Idempotency keys

Prevent duplicate jobs with idempotency_key:

curl -X POST https://api.chronos.sh/v1/jobs \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Charge invoice inv_789",
    "handler": "charge-invoice",
    "delay": { "value": 1, "unit": "hour" },
    "idempotency_key": "charge-inv_789",
    "payload": { "invoiceId": "inv_789" }
  }'

If a job with the same idempotency_key already exists on your account, the API returns 409 with code idempotency_key_conflict instead of creating a duplicate.

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 account and persists for the lifetime of the job. Max 255 characters.

Push delivery for one-off jobs

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

curl -X POST https://api.chronos.sh/v1/jobs \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Send webhook notification",
    "handler": "notify",
    "delay": { "value": 5, "unit": "minute" },
    "delivery": {
      "type": "push",
      "http": {
        "url": "https://your-app.com/hooks/chronos",
        "method": "POST"
      }
    },
    "payload": { "event": "subscription.created", "data": { "id": "sub_123" } }
  }'

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

Configuring retries and timeout

Override defaults per job:

{
  "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.

Querying one-off jobs

Filter the job list to show only one-off jobs (those without a parent schedule):

curl "https://api.chronos.sh/v1/jobs?schedule_id=null" \
  -H "Authorization: Bearer chrns_your_api_key"

The literal string "null" filters for jobs where schedule_id is null.