Skip to main content

FAQ

Frequently asked questions about Scheduler0, its features, and how to use it effectively.

General​

What is Scheduler0?​

Scheduler0 is a cloud-native platform for scheduling and executing cron jobs. It lets teams schedule recurring or one-off tasks across any cloud provider (AWS, GCP, Azure) or on-premises infrastructure, monitor every execution in real time, and recover automatically from failures — all without managing cron infrastructure themselves.

How is Scheduler0 different from pg-cron, AWS EventBridge, or GCP Cloud Scheduler?​

Unlike cloud-provider-specific solutions, Scheduler0 is cloud-agnostic. It uses SQLite and Raft consensus for storage, so it has no dependency on any cloud provider's database or event bus. This means:

  • You can run it on any cloud or on-premises without lock-in.
  • You can migrate between providers without re-creating your job configs.
  • You get a single unified API, dashboard, and SDK regardless of where your executors live.

Does Scheduler0 offer a managed service or do I need to self-host?​

Both options are available:

  • Managed service — Scheduler0 hosts and operates the platform for you. Sign up at scheduler0.com, create credentials, and start scheduling immediately. Available on the Free and Paid plans.
  • Self-hosted — Deploy the Go binary on your own infrastructure for full control over data and configuration. Self-hosting requires the Paid or Teams plan.

For dedicated infrastructure, SSO, and custom SLAs, see the Teams and Enterprise deployment options.

Core Concepts​

What is the resource hierarchy?​

Account
  ├── Credentials  (API key/secret pairs for authentication)
  ├── Projects     (groups of related jobs)
  │     └── Jobs  (scheduled tasks)
  └── Executors   (how and where jobs run)
                └── Executions (logs of every job run)
  • Account — the top-level owner of all resources. Tracks execution quota and AI token balance.
  • Project — an organizational container for jobs, similar to a namespace.
  • Job — the core scheduling unit: a cron spec (or one-off start date) plus a payload and an executor.
  • Executor — defines how the job runs: a webhook URL, a cloud function, or a local shell command.
  • Credential — an API key + secret pair with scopes that controls what a caller can do.
  • Execution — a single recorded run of a job (scheduled / success / failed).

What is a Project?​

A Project is a logical container for jobs. It has a name, optional description, and belongs to one account. Use projects to separate environments (e.g. production, staging) or product areas (e.g. billing, notifications). See Projects.

What is an Executor?​

An Executor tells Scheduler0 how to invoke a job. Three types are supported:

TypeDescription
webhook_urlScheduler0 sends an HTTP request to your endpoint when the job fires
cloud_functionScheduler0 invokes an AWS, GCP, or Azure cloud function directly
localThe Scheduler0 CLI pulls jobs and runs a shell command on your machine

See Executors.

Authentication​

How do I authenticate API requests?​

All standard API requests require three headers:

X-API-Key: <your api key>
X-Secret-Key: <your plaintext secret>
X-Account-ID: <your account id>

You create credentials in the Scheduler0 dashboard or via POST /credentials. On creation the response includes plaintextSecret — save it immediately, it is shown only once and cannot be retrieved again.

The healthcheck endpoint (GET /healthcheck) requires no authentication.

What credential scopes are available?​

ScopeAllows
readGET requests on jobs, projects, credentials, executors, executions, async tasks, features, and AI settings
writePOST/PUT/DELETE on jobs, projects, credentials, executors, and AI settings; registering a local executor
executeCalling POST /prompt (AI scheduling), reporting local execution results, and cleaning up old execution logs

A request with a valid credential but the wrong scope returns 403 with the message credential missing required scope: <scope>. See Credentials.

When do credentials expire?​

User-created credentials expire 90 days after creation. The server sets expiresAt automatically — it is not user-overridable. Requests with an expired credential return 401.

A background sweep on the Raft leader automatically archives expired credentials, so you do not need to clean them up manually.

How do I rotate an expiring credential?​

  1. Create a new credential and save the returned apiKey and plaintextSecret.
  2. Roll out the new key/secret to your services.
  3. Archive the old credential.
# Create replacement
scheduler0 credentials create --created-by "user123" --scopes "read,write,execute"

# Archive old credential
scheduler0 credentials archive <old-id> --archived-by "user123"

Or use POST /credentials and POST /credentials/{id}/archive via the REST API. See Credentials — Rotating Credentials.

What is Basic Auth and when is it used?​

Basic Auth (username + password from your Scheduler0 configuration, plus an X-Peer header) is used only for self-hosted deployments to access admin-only endpoints: /accounts/*, /features, /async-tasks/*, /cluster/*, and POST /credentials/rotate-secret. The managed service does not expose these endpoints.

Scheduling​

What cron format does Scheduler0 use?​

Scheduler0 uses the robfig/cron library, which extends the standard 5-field cron format with a leading seconds field:

* * * * * *
│ │ │ │ │ └── day of week (0–6, Sun–Sat)
│ │ │ │ └──── month (1–12)
│ │ │ └────── day of month (1–31)
│ │ └──────── hour (0–23)
│ └────────── minute (0–59)
└──────────── second (0–59)

You can also use predefined macros (@yearly, @monthly, @weekly, @daily, @hourly) and interval expressions (@every 5m, @every 1h30m).

See Jobs — Cron Specification for a full table of examples.

How do I set the timezone for a job?​

Set the timezone field to a valid IANA timezone name:

{
  "spec": "0 0 9 * * *",
  "timezone": "America/New_York"
}

Alternatively, use timezoneOffset (in minutes from UTC) if an IANA name is not available. When neither is supplied the job runs in UTC.

Can I schedule a one-off (non-recurring) job?​

Yes. Omit the spec field and set startDate to the desired run time:

{
  "projectId": 1,
  "executorId": 2,
  "startDate": "2025-01-01T08:00:00Z",
  "timezone": "UTC",
  "createdBy": "user123"
}

The job fires once at startDate and does not recur.

Can I pause and resume a job without deleting it?​

Yes. Update the job's status field:

  • "status": "inactive" — job is paused and will not execute
  • "status": "active" — job is running normally
curl -X PUT "https://api.scheduler0.com/v1/jobs/1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_API_SECRET" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -d '{"status": "inactive", "modifiedBy": "user123"}'

Can I change the cron schedule of an existing job?​

The spec field is immutable once a job is created. To change the schedule, delete the existing job and create a new one with the updated spec.

Execution & Executors​

How does job execution work?​

Scheduler0 queues each job according to its cron spec. At the scheduled time it dispatches the job to the configured executor:

  • webhook_url executors: Scheduler0 makes an HTTP request to your endpoint.
  • cloud_function executors: Scheduler0 invokes the cloud function directly using the credentials you provided.
  • local executors: The Scheduler0 CLI running on your machine polls for due jobs, runs the shell command, and batch-reports results back every 5 minutes or after 50+ logs.

Is job creation synchronous?​

No. POST /jobs returns 202 Accepted with an async requestId:

{ "success": true, "data": "request-id-abc123" }

The Location response header points to /async-tasks/request-id-abc123. Self-hosted users can poll that endpoint. On the managed service, verify job creation by listing or retrieving the job directly after a short delay.

How does retry logic work?​

When a job execution fails, Scheduler0 retries it automatically up to retryMax times. Plan limits apply:

PlanMaximum retryMax
Free3
Paid15

Set "retryMax": 0 to disable retries entirely. Each retry attempt is tracked via an incrementing executionVersion field in the execution log.

What execution states exist?​

StateInteger valueMeaning
scheduled0The job has been queued but not yet run
success1The execution completed successfully
failed2The execution failed (all retries exhausted)

The state field in execution log responses is an integer.

Observability​

How do I view execution history?​

Query GET /executions with optional filters:

curl "https://api.scheduler0.com/v1/executions?jobId=789&state=failed&limit=50&offset=0" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_API_SECRET" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID"

Filterable by jobId, projectId, state, date range (startDate/endDate), with pagination up to 100 results per page. See Jobs — Execution Logs.

How long are execution logs retained?​

PlanRetention
Free30 days
Paid90 days

You can also trigger a manual cleanup via POST /executions/cleanup-old-logs (requires execute scope) and pass a custom retentionMonths value.

Is there an analytics endpoint?​

Yes. GET /executions/analytics returns per-minute execution counts (scheduled / success / failed) for a given time window, useful for visualizing throughput over time. GET /executions/totals returns lifetime totals for the account.

AI Scheduling​

What is AI scheduling?​

The POST /prompt endpoint lets you describe a schedule in plain English and receive a structured job configuration in return. For example: "Send a weekly digest every Monday at 9 AM Eastern" returns a fully formed job config with cron spec, timezone, and kind (DIGEST).

This feature requires the execute scope and sufficient token balance.

How are AI scheduling tokens consumed?​

Each call to POST /prompt costs 1 credit. If the account has insufficient tokens the API returns 402. Credits consumed by a prompt are not refunded if you choose not to use the returned job config.

To add tokens (self-hosted), use PUT /accounts/{id}/tokens/add. Check your current balance at GET /accounts/{id}/tokens.

Can I use my own AI model?​

Yes — Scheduler0 supports BYOK (Bring Your Own Key). Configure your preferred model provider and API key via GET/PUT /account/ai-settings. Supported providers: OpenAI, Anthropic, and AWS Bedrock.

Plans & Limits​

What are the plan limits?​

LimitFreePaid ($49/mo)
Executions per month1,000100,000
Job payload (data)3 KB1 MB
Max retries (retryMax)315
Execution log retention30 days90 days

Teams and Enterprise plans offer custom execution limits and deployment options. Contact us for details.

What is the API pagination limit?​

List endpoints (/jobs, /projects, /credentials, /executors, /executions) accept limit (1–100, default 10) and offset query parameters.

Where can I track my monthly execution usage?​

Your account's current execution count and the next reset date are available at GET /accounts/{id}/execution-count (self-hosted Basic Auth) or visible in the Scheduler0 dashboard.

SDKs & CLI​

Which official clients are available?​

ClientInstall
Gogo get github.com/scheduler0/scheduler0-go-client
Node.js / TypeScriptnpm install @scheduler0/scheduler0-node-client
Pythonpip install scheduler0-python-client
CLIDownload from the CLI docs
RESTFull OpenAPI spec at api-reference.scheduler0.com

Terraform support is also available for infrastructure-as-code workflows.

Which SDK should I use for the local executor?​

The Go client and the CLI have first-class local executor support (register, pull jobs, report results). The Node.js and Python clients cover the full API surface but do not include dedicated local executor helpers; use the REST API or CLI directly for those operations.

Job creation returns 202 — how do I know when jobs are ready?​

POST /jobs is asynchronous. The response body contains the requestId and the Location header points to /async-tasks/{id}. Self-hosted users can poll that endpoint until it returns the completed task. On the managed service, list or retrieve the job directly a moment after the request returns.

Self-Hosting​

note

Self-hosting Scheduler0 requires the Paid or Teams plan. The Free plan is for the managed service only.

What does Scheduler0 use for storage?​

Scheduler0 uses SQLite for data storage and Raft consensus for distributed coordination. This avoids dependency on any cloud provider's database and allows multi-node high-availability deployments without external message queues.

Which endpoints are self-hosted only?​

The following require Basic Auth (Authorization: Basic ..., X-Peer: cmd):

  • /accounts/* — account management (create, features, execution counts, tokens)
  • /features — system feature flags
  • /async-tasks/{id} — async operation polling
  • /cluster/* — Raft node management, backup, restore
  • POST /credentials/rotate-secret — server-side secret key rotation

How does backup and restore work?​

Backup and restore use the SQLite Online Backup API and are initiated from the Raft leader node only. Backups can be stored to S3. A safety backup is automatically taken before a restore is applied. See Backup and Restore.

API Reference​

For the full API specification with request/response schemas for every endpoint, see the Scheduler0 API Reference.