Scheduled Jobs & Cron

Deploy background jobs that run on a cron schedule. Your code executes on schedule, scales to zero between runs, and you pay only for execution time.

How It Works

When you deploy with --schedule, Telbase creates a GCP Cloud Run Job (your code) and a Cloud Scheduler trigger (the cron). On each scheduled tick, Cloud Scheduler runs your job. When it finishes, the container shuts down — no idle compute.

telbase deploy --schedule "0 * * * *"

Deploying a Scheduled Job

# Deploy a job that runs every hour
telbase deploy --schedule "0 * * * *"

# Weekdays at 9 AM Eastern
telbase deploy --schedule "0 9 * * 1-5" --schedule-timezone "America/New_York"

# Every 15 minutes (UTC, the default)
telbase deploy --schedule "*/15 * * * *"

Flags

• --schedule <cron> — 5-field cron expression. Required to deploy as a scheduled job.
• --schedule-timezone <tz> — IANA timezone (default: UTC). Examples: America/New_York, Europe/London, Asia/Tokyo.

Daemon vs Task Workers

Not all background workers should be scheduled jobs. Telbase scans your code for long-running patterns and classifies workers into two types:

Deploying a Daemon Worker

If Telbase detects a daemon pattern, deploy as a regular Cloud Run Service with Always On enabled:

1. Deploy without --schedule — this deploys as a Cloud Run Service (not a Job).
2. Add a health endpoint if your worker doesn't serve HTTP. Cloud Run requires a process listening on $PORT:

# Add to your worker entrypoint — Cloud Run requires $PORT listener
import threading, http.server, os
threading.Thread(target=lambda: http.server.HTTPServer(
    ('', int(os.environ.get('PORT', 8080))),
    http.server.BaseHTTPRequestHandler
).serve_forever(), daemon=True).start()

3. Enable Always On in Dashboard → Settings, or via POST /projects/:id/warm-start. Without Always On, Cloud Run scales to zero on idle — killing the daemon.

Refactoring Daemons to Scheduled Tasks

If all your daemon's jobs are periodic (hourly, daily, weekly), you can refactor to a one-shot dispatcher. Each invocation runs, does its work, and exits — 10-100x cheaper than Always On for infrequent work.

# worker.py — one-shot dispatcher for Cloud Run Jobs
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]()

telbase deploy --schedule "0 * * * *" --command "python worker.py fetch"

Managing Jobs

After deploying, manage your job from the dashboard or CLI.

Dashboard

The Jobs tab shows your schedule (in human-readable format), a Run Now button for manual triggers, and a toggle to pause/resume the schedule.

CLI

# Manually trigger an execution
telbase run

# Trigger and stream logs in real-time
telbase run --follow

# Update the schedule (redeploy with new cron)
telbase deploy --schedule "0 12 * * *"

API

• PATCH /projects/:id/schedule — update cron expression or timezone
• POST /projects/:id/schedule/pause — pause the schedule
• POST /projects/:id/schedule/resume — resume a paused schedule

Execution History

View past executions and their status from the CLI or dashboard.

# Show recent execution history
telbase logs --executions

The dashboard Jobs tab displays each execution with a color-coded status indicator, duration, and a link to view logs.

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 click Resume in the dashboard or call POST /projects/:id/schedule/resume.

Pricing

Each scheduled job uses one slot. Slots are included in your plan. Extra slots and execution compute are charged via credits.

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. Returns an execution ID for status polling.
• 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 — --schedule, telbase run, and --executions flag documentation
• Plans & Usage — slot limits, credits, and tier details
• Claude Code — MCP tools for deploying and managing jobs from AI conversations
• Troubleshooting — circuit breaker, timeout, and common job issues