# Chronos

> Chronos is a managed scheduling API. Define when jobs run, we make sure they happen.

Chronos runs recurring schedules (cron or interval) and one-off delayed jobs, and delivers each job to your code by HTTP push or to a worker that pulls over long-poll. It never runs your code. Each schedule occurrence produces at most one job, and delivery is at-least-once with retries, so handlers must be idempotent.

Facts to know before calling the API:

- Base URL `https://api.chronos.sh`, routes under `/v1`, header `Authorization: Bearer <key>`. Every example reads the key from the `CHRONOS_API_KEY` environment variable.
- An API key cannot create or manage keys. A signed-in human with the admin role creates one in the dashboard at https://app.chronos.sh under Settings → API Keys.
- `POST /v1/jobs` creates a one-off job that runs as soon as possible unless you set `delay` or `scheduled_for`. `POST /v1/schedules` creates a recurring schedule; an interval schedule first runs one interval after creation (at least 10 minutes on the Free plan) and a cron schedule at its next matching time. `POST /v1/schedules/{id}/trigger` runs it now.
- The Node SDK `@chronos.sh/sdk` has the pull worker and the push `Webhook` verifier. It has no client for creating schedules or jobs; use REST with curl or fetch.
- Push delivery signs each request. Verifying the signature needs the signing secret, which an API key cannot read.
- Plans: Free $0/mo (3 schedules, 2,500 executions/month), Solo $9.99/mo (25 schedules, 25,000 executions/month), Team $29.99/mo (100 schedules, 250,000 executions/month), Business $79.99/mo (500 schedules, 1,000,000 executions/month). Full table on the Pricing & Limits page.

## Overview
- [Overview](https://chronos.sh/docs): Chronos is a managed scheduling API. Define when jobs run, we make sure they happen.

## Quick Start
- [Pull (Worker)](https://chronos.sh/docs/quick-start/pull): Run a worker that fetches jobs from Chronos. Get your first job running in under 5 minutes.
- [Push (HTTP)](https://chronos.sh/docs/quick-start/push): Receive jobs via HTTP push from Chronos. Get your first job running in under 5 minutes.

## Agents
- [Agent Setup](https://chronos.sh/docs/agents/setup): Hand a coding agent one prompt and an API key. It reads the docs, wires up a worker, and gets a job running.

## Guides
- [Worker Setup](https://chronos.sh/docs/guides/sdk-worker-setup): Configure and run a Chronos worker for production pull delivery.
- [Push Delivery](https://chronos.sh/docs/guides/push-delivery): Set up HTTP push delivery so Chronos calls your HTTP endpoint.
- [Signature Verification](https://chronos.sh/docs/guides/signature-verification): Verify push delivery signatures to ensure requests come from Chronos.
- [One-Off Jobs](https://chronos.sh/docs/guides/one-off-jobs): Schedule delayed one-time jobs without a recurring pattern.
- [Scheduling Patterns](https://chronos.sh/docs/guides/scheduling-patterns): Cron expressions and interval patterns for recurring schedules.
- [Retries & Error Handling](https://chronos.sh/docs/guides/retries-error-handling): How Chronos retries failed jobs with exponential backoff.
- [Idempotent Handlers](https://chronos.sh/docs/guides/idempotent-handlers): Design job handlers that are safe to run more than once.
- [Graceful Shutdown](https://chronos.sh/docs/guides/graceful-shutdown): Shut down workers without dropping in-flight jobs.

## Concepts
- [Schedules, Jobs & Executions](https://chronos.sh/docs/concepts/schedules-jobs-executions): The core mental model: how schedules spawn jobs and track executions.
- [Delivery Methods](https://chronos.sh/docs/concepts/delivery-methods): Push vs pull: how Chronos delivers jobs to your code.
- [Guarantees](https://chronos.sh/docs/concepts/guarantees): Exactly-once scheduling, at-least-once delivery, and what they mean.

## Reference
- [Node.js SDK](https://chronos.sh/docs/reference/node-sdk): Complete API reference for the @chronos.sh/sdk package.
- [REST API](https://chronos.sh/docs/reference/rest-api): Full HTTP API reference. Endpoints, request/response shapes, and errors.
- [Error Codes](https://chronos.sh/docs/reference/error-codes): All error codes returned by the Chronos API and SDK.

## Pricing & Limits
- [Pricing & Limits](https://chronos.sh/docs/pricing-limits): Plan tiers, rate limits, and usage quotas.

## Documentation Sets

- [Abridged documentation](https://chronos.sh/llms-small.txt): a compact version of the documentation for Chronos, with non-essential content removed
- [Complete documentation](https://chronos.sh/llms-full.txt): the full documentation for Chronos

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation