Scheduled Jobs & Cron

Run background tasks on a cron schedule. Your code runs on schedule, nothing runs between runs, and you pay only for execution time.

How It Works

A Telbase scheduled job is a Google Cloud Run job that Telbase starts on a cron schedule. It runs once, does its work, and exits; exit code 0 is a success. Between runs nothing is running.

Your coding agent sets one up when the app has a task that runs on a timer: a script the README or a crontab runs on a schedule, a GitHub Actions schedule: workflow, or a scheduler inside the web process (node-cron, APScheduler, setInterval). A scheduler inside the web process does not run reliably on Telbase, so the agent offers to move it into a job.

Creating a Scheduled Job

1. Reserve the job: five cron fields, in the time zone given (UTC by default). The answer gives the job's deploy command.

telbase jobs create my-app nightly-report --schedule "0 6 * * *" --timezone Europe/Paris

2. Deploy it from the directory that holds its code, with the command from the answer. What runs is the image's start command: a Procfile line, the Dockerfile's CMD, or --command / --args.

telbase gcloud run jobs deploy <name> --source . --region us-central1   --task-timeout 300s --max-retries 0 --quiet   --command python --args scripts/report.py

3. Run it once and check that the run succeeded. Telbase creates the schedule as soon as the job exists.

telbase jobs run nightly-report
telbase jobs executions nightly-report

Vercel crons

A Vercel app can instead have Vercel call one of its routes on a schedule, with crons in vercel.json (UTC; the work must finish within the function's time limit). Each cron takes one job slot. telbase jobs list shows whether they are on.

{
  "crons": [{ "path": "/api/digest", "schedule": "0 6 * * *" }]
}

Workers that never exit

A job must exit. A worker that runs forever (a queue consumer, a scheduler loop) is not hosted: Cloud Run scales to zero between requests. When all its work is periodic, it becomes a one-shot dispatcher that runs, does its work, and exits:

# worker.py — one-shot dispatcher for a scheduled job
import sys
from tasks import fetch_data, generate_report, sync_inventory

dispatch = {"fetch": fetch_data, "report": generate_report, "sync": sync_inventory}
task = sys.argv[1] if len(sys.argv) > 1 else "fetch"
dispatch[task]()

Deployed with --command python --args worker.py,fetch, one job per task.

Managing Jobs

telbase jobs list                                  # jobs, Vercel crons and slots
telbase jobs info nightly-report
telbase jobs run nightly-report                    # run it now
telbase jobs schedule nightly-report --schedule "0 12 * * *"
telbase jobs pause nightly-report
telbase jobs resume nightly-report
telbase jobs delete nightly-report --yes           # removes it with its schedule

Execution History

# A job's recent runs, newest first
telbase jobs executions nightly-report

# Its logs
telbase gcloud logging read 'resource.type="cloud_run_job" AND resource.labels.job_name="<name>"' --freshness=1d

Circuit Breaker

If your job fails 5 consecutive times, Telbase automatically pauses the schedule and sends you an email notification. This prevents runaway costs from a broken job.

To resume: fix the underlying issue, then run telbase jobs resume <job>.

Pricing

Each scheduled job uses one slot. Slots are included in your plan. Extra slots and execution compute are charged via credits. A job holds its slot until you delete it: a paused job keeps its slot, and an extra slot is charged every month, paused or not.

Execution compute: 1 credit = 25 compute-minutes. Fractional credits accumulate within a billing cycle.

Cron Syntax Reference

Telbase uses standard 5-field cron format: minute hour day month weekday.

MCP Tools

When using Claude Code with the Telbase MCP server, five tools are available for scheduled jobs:

• get_job_executions — list execution history for a scheduled job, including status, timestamps, and duration.
• run_scheduled_job — manually trigger a scheduled job.
• pause_job — pause a scheduled job's cron schedule. The job remains deployed but won't execute until resumed.
• resume_job — resume a paused scheduled job. Restores the cron schedule.
• update_schedule — update the cron expression or timezone for a scheduled job without redeploying.

Next Steps

• CLI Reference — the telbase jobs commands
• Plans & Usage — slot limits, credits, and tier details
• Claude Code — MCP tools for managing jobs from AI conversations
• Troubleshooting — circuit breaker, timeout, and common job issues