Background Jobs

Background jobs let you run code on a schedule without managing a separate scheduler or worker process. Define a cron expression, point it at an edge function, and OrbitNest handles the rest.

How it works

A background job is a named schedule attached to a project. When the cron expression fires, OrbitNest invokes the associated edge function with the project's environment variables and execution context. Results, duration, and any errors are recorded in the run history.

Creating a job

You can create jobs from the Studio dashboard (Project → Background Jobs → New Job) or via the REST API:

curl -X POST \
  https://studio.orbitnest.io/api/admin/projects/{projectId}/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-report",
    "function_name": "generate-report",
    "schedule": "0 9 * * *",
    "timezone": "America/New_York",
    "timeout": 60,
    "enabled": true
  }'

Cron expressions

Standard five-field cron syntax: minute hour day-of-month month day-of-week. The minimum interval is 1 minute. All schedules support IANA timezone names (e.g. Europe/London, Asia/Tokyo).

• */5 * * * * — every 5 minutes
• 0 9 * * 1-5 — 9 AM weekdays
• 0 0 1 * * — midnight on the 1st of each month
• 30 */2 * * * — every 2 hours at the 30-minute mark

Execution configuration

Timeout

Choose from 10s, 30s, 60s, or 120s. If the function exceeds the timeout, the run is terminated and marked as failed.

Concurrency

Set a max_concurrent_runs value to prevent overlapping executions. If a scheduled run fires while the previous run is still active and the limit is reached, the new run is skipped.

Execution context

When a job fires, the associated edge function receives a context object containing the project info, environment variables, request metadata, and the job name. This lets a single function serve multiple jobs with different behavior.

Manual triggers

Trigger any job on demand from the dashboard or the API. Manual runs bypass the schedule but respect timeout and concurrency settings.

curl -X POST \
  https://studio.orbitnest.io/api/admin/projects/{projectId}/jobs/daily-report/trigger \
  -H "Authorization: Bearer $TOKEN"

Run history

Every run is logged with its status (success, failed, timeout), duration, trigger type (scheduled or manual), and any error messages or result JSON. The dashboard shows the last 50 runs per job.

Limits

• Up to 10 jobs per project.
• Minimum schedule interval: 1 minute.
• Maximum execution timeout: 120 seconds.
• Run history retention: last 50 runs per job.