Delivery Methods

Chronos supports two ways to deliver jobs to your code: push (HTTP) and pull (worker).

Every schedule or job uses exactly one delivery method. Both paths get identical retry guarantees and execution tracking.

Push vs Pull

	Push (HTTP)	Pull (Worker)
How it works	Chronos sends an HTTP request to your endpoint	Your worker long-polls Chronos for jobs
You provide	A publicly reachable HTTPS URL	A running process (SDK or custom HTTP client)
Delivery config	{ type: "push", http: { url, method } }	{ type: "pull" } (or omit, the default)
Best for	Serverless, existing servers, event-driven architectures	Background workers, long-running processes, environments without public URLs

Both paths get identical retry guarantees and execution tracking.

Which to choose

Use push if you:

• Run serverless functions (Vercel, Netlify, Lambda, Cloudflare Workers)
• Have a long-running server that can expose an endpoint
• Want the least infrastructure (no worker process to manage)

Use pull if you:

• Are behind a firewall, NAT, or have no public URL
• Run a dedicated background worker process
• Want control over concurrency (one job at a time per worker)

Tip

You can mix delivery methods. Different schedules can use different types. You can also change a schedule’s delivery method after creation via PATCH.

Push delivery flow

Chronos                              Your endpoint
  │                                       │
  ├── Job is due ────────────────────────▶│
  │   POST https://your-app.com/hook      │
  │   + signature headers                 │
  │                                       │
  │◀──────────────────────── 200 OK ──────┤
  │                                       │
  └── Execution: completed                │

1. Job becomes due at its run_at time
2. Chronos makes an HTTP request to your configured URL
3. Your endpoint does the work and returns a status code
4. 2xx = success, 5xx/timeout = retry, 4xx = terminal failure

See Push Delivery for the full setup guide.

Pull delivery flow

Your worker                           Chronos
  │                                       │
  ├── POST /v1/worker/jobs/claim ────────▶│
  │   (long-poll, up to 20s)              │
  │                                       │
  │◀──────────────────── Job claimed ─────┤
  │                                       │
  │   [handler runs]                      │
  │                                       │
  ├── POST /v1/worker/executions/:id/result ──▶│
  │   { status: "completed" }                  │
  │                                       │
  └── Poll again...                       │

1. Your worker calls the claim endpoint (SDK does this automatically)
2. Chronos holds the connection until a job is available (up to 20 seconds)
3. A job is returned, your handler runs
4. Your worker reports the result back
5. Loop continues

See Worker Setup for the full setup guide.

What each side handles

Responsibility	Push	Pull
Triggering execution	Chronos (HTTP request)	Your worker (claim request)
Running your code	Your server	Your worker process
Reporting success/failure	Your HTTP response code	SDK reports automatically
Retry scheduling	Chronos (on 5xx/timeout)	Chronos (on handler error or timeout)
Timeout detection	Chronos (HTTP timeout)	Chronos (lease expiry sweep)
Concurrency	Unlimited (Chronos makes requests as jobs come due)	One job at a time per worker instance
Signature verification	You verify X-Chronos-Signature	Not applicable (API key auth)

Pull job states

Pull delivery introduces an extra state compared to push:

pending → admitting → queued → ready → running → completed/failed

The ready state means “available to be claimed.” A job sits in ready until a worker picks it up. Push jobs skip ready entirely. They go from queued directly to running when dispatched.

Timeout handling

Push: If your endpoint doesn’t respond within the job’s timeout (default 30 seconds), Chronos marks the execution as timeout and schedules a retry.

Pull: The SDK does not enforce timeouts. Your handler can run as long as needed. However, Chronos monitors a lease on the server side. If no result is reported within timeout seconds of claiming, a background sweep marks the execution as timeout and schedules a retry.

In both cases: if you need your handler to run longer than 30 seconds, increase timeout on the schedule or job.