Skip to main content

​
What are Background Jobs?

Background Jobs are OpenSink’s built-in scheduling mechanism.
They let you trigger HTTP endpoints on a fixed interval — reliably, visibly, and without running your own cron infrastructure.
Background Jobs exist to remove one of the most painful parts of automation:
“Where do I host this cron, why didn’t it run, and how do I debug it?”
OpenSink handles scheduling, execution tracking, and visibility — you own the logic.

​
What Background Jobs Are (and Aren’t)

What they are

  • Reliable HTTP schedulers
  • Minutes-based intervals
  • Inspectable execution history
  • Agent- and automation-friendly

What they are not

  • Workflow engines
  • Code execution environments
  • Task queues
  • Event processors
Background Jobs trigger work — they don’t perform it.

​
Typical Use Cases

AI Agents

Periodically run an agent:
  • Daily research
  • Market scanning
  • Monitoring tasks

Automation

Trigger internal systems:
  • Sync data
  • Refresh caches
  • Poll APIs

Reporting

Generate outputs on a schedule:
  • Daily summaries
  • Status reports
  • Health checks

​
How Scheduling Works

OpenSink uses simple, opinionated scheduling — not cron strings.
This is intentional. Cron expressions are powerful, but they allow unsafe patterns (every second, overlapping runs, etc.).
Each job defines:
  • Interval (minutes)
  • Start minute (alignment within the hour)

​
Examples

IntervalStart minuteRuns at
15 min000, 15, 30, 45
30 min505, 35
60 min0Every hour
120 min10Every 2 hours, at :10
This keeps scheduling predictable and safe.

​
Configuring a Job

1

Name your job

Give it a human-readable name so you can recognize it later.
2

Choose schedule

  • Interval (minutes)
  • Start minute
3

Define the HTTP request

Configure:
  • Request URL
  • HTTP method
  • Headers (optional)
  • Body (optional)
4

Enable or disable

Jobs can be paused instantly without deleting them.

​
Execution Visibility

Every time a job runs, OpenSink records a Job Run.

What you can see

  • Run status (success / failure)
  • Execution time
  • HTTP response status
  • Error messages

Why this matters

  • No silent failures
  • No guesswork
  • Clear audit trail
  • Easy debugging
Each job shows:
  • total runs
  • successful runs
  • failed runs
  • last run time
  • next scheduled run

​
Jobs + Sessions (How They Work Together)

Jobs and Sessions are complementary, not overlapping.
A common pattern:
  1. Background Job runs on a schedule
  2. Job calls your agent’s execution endpoint
  3. Agent creates or resumes a Session
  4. Session produces Items or requests input
Jobs trigger execution
Sessions record execution

​
Example: Daily Trading Agent

1

Create a Background Job

Runs every morning at 09:00.
2

Job calls agent endpoint

The job triggers: POST /agents/trading-bot/execute
3

Agent logic runs

  • Fetches market news
  • Analyzes signals
  • Creates a Session
4

Session requests approval

Agent pauses and waits for human confirmation.
This entire flow runs without servers, cron, or schedulers on your side.

​
Design Principles

Background Jobs are intentionally constrained.
They:
  • only schedule HTTP calls
  • do not execute user code
  • do not manage retries or workflows
  • do not interpret responses
This keeps them:
  • reliable
  • debuggable
  • predictable

​
When to Use Background Jobs

Use Jobs when:
  • execution must happen on a schedule
  • reliability matters
  • visibility matters
  • you don’t want to manage cron
Don’t use Jobs when:
  • execution is event-driven
  • you need real-time guarantees
  • you’re orchestrating workflows

​
Summary

Background Jobs

Reliable, visible schedulers that trigger work.

Sessions

Durable execution records that track what happened.
Together, they let you build production-grade agents without infrastructure overhead.