Cron Jobs

Use cron jobs to run scheduled HTTP requests to your application endpoints at regular intervals. Define them in your globe.yaml file and they'll execute automatically on your production deployment without requiring a separate job runner.

How Cron Jobs Work

Cron jobs in Globe:

• Execute HTTP requests to specific endpoints in your application
• Only run on production deployments (not preview or development)
• Are synchronized with each successful production deployment
• Run in UTC timezone only

How to Manage Cron Jobs

Once defined, cron jobs are visible in your Globe dashboard after a production deployment. If a job no longer appears in your globe.yaml, it becomes inactive and stops running until re-added.

To view and manage your cron jobs:

1. From your Globe dashboard, navigate to your project
2. Navigate to Cron Jobs
3. View your defined cron jobs by Active and Inactive status

How to Define a Cron Job

Define cron jobs in your globe.yaml file. Here's a simple example:

crons:
  - id: refresh_auth_token
    schedule: "*/45 * * * *"
    path: "/auth/refresh" # This is the application endpoint that Globe will call

This example schedules a POST request to your application's /auth/refresh endpoint every 45 minutes. The path value is the HTTP route in your application that Globe will call. For more details on cron syntax, see the unix-cron documentation.

How to Handle Cron Job Requests

Each cron job triggers a HTTP POST request to the specified path. You need to write a route handler in your application to process these requests.

Here's an example using shelf_router:

import 'package:shelf_router/shelf_router.dart';

final app = Router();

app.post('/auth/refresh', (Request request) async {
  // Your handler for the endpoint defined in globe.yaml
  // Logic to refresh the auth token
  return Response.ok('ok');
});

If your handler returns a status code outside the 2xx range, it will be displayed as an error on the Globe dashboard.

Cron Job IDs

The id field represents the unique identifier of the cron job. It is used to manage job states and view logs in the dashboard.

• The list cannot contain duplicate IDs
• Maximum length: 50 characters
• Allowed characters: a-z, 0-9, and _

If a job is removed and later re-added with the same ID, its log history will persist.

Best Practices

• Name cron jobs clearly (e.g., refresh_auth_token, db_cleanup)
• Use tools like crontab.guru to help design cron expressions
• Monitor jobs via the dashboard to catch issues early
• Consider logging actions/failures in cron handlers for easier observability

Related Topics

• The globe.yaml File - Define cron jobs in your project configuration
• Deployments - Understand how cron jobs run on production deployments
• Schedule Cron Jobs on Globe - Step-by-step guide for setting up cron jobs