Skip to main content

vercel-schedules

Python SDK for Vercel Schedules.

pip install vercel-schedules

Declare schedules in code

@schedule declares a function as the handler of a recurring schedule:

# jobs.py
from vercel.schedules import Cron, ScheduleMetadata, schedule


@schedule(cron=Cron(hour=3))
def reindex() -> None:
    ...


@schedule(cron="*/15 * * * *", name="sync-billing", timezone="America/New_York")
async def sync_billing(metadata: ScheduleMetadata) -> None:
    print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")

Deploy them by naming the module in vercel.json. The cron, timezone, and jitter come from the code, so the entry sets only the root the schedule runs in and the module path, relative to it:

{
  "schedules": {
    "jobs": { "root": ".", "entrypoint": "jobs" }
  }
}

The build imports jobs from the root and creates a schedule for each @schedule it registers, including those in modules it imports. Each schedule is named after the entry and the schedule, such as jobs.reindex and jobs.sync-billing. Use that name with get_schedule() and the other management functions, and expect it in metadata.name.

The schedule name defaults to the function's name and must be unique among the schedules the module registers. Renaming a schedule replaces it. A handler may be a coroutine function. A parameter annotated ScheduleMetadata receives the firing's metadata, under any name. A firing supplies nothing else, so every other parameter needs a default.

To run one function on several schedules, stack @schedule and name each one:

@schedule(cron="0 3 * * *", name="report-morning")
@schedule(cron="0 15 * * *", name="report-afternoon")
def report(metadata: ScheduleMetadata) -> None:
    ...

Function settings

A schedule can set how long a firing may run and the regions its function is deployed to:

from datetime import timedelta


@schedule(cron=Cron(hour=4), max_duration=timedelta(minutes=15), regions=["fra1"])
def export_reports() -> None:
    ...

max_duration is a whole number of seconds, up to your plan's limit, and defaults to the platform's default. Each firing runs once, in one of the regions: the others are used only if it is unavailable, so pass one region to choose where the schedule runs. regions defaults to the project's regions.

Schedules with the same settings run in one function, and each other combination runs in a function of its own. Schedules in different functions do not share a process, so they do not share module-level state such as a cache or a connection pool.

Importing the module registers its schedules. get_registered_schedules() returns them, and RegisteredSchedule.run(metadata) calls the handler for one firing: a coroutine function is awaited, and a regular function runs in a worker thread, with any awaitable it returns awaited too.

To handle a firing in your own route, such as a schedule that targets a path, read it from the request headers with ScheduleMetadata.from_headers():

from fastapi import FastAPI, Request
from vercel.schedules import ScheduleMetadata

app = FastAPI()


@app.post("/api/cleanup")
async def cleanup(request: Request) -> None:
    metadata = ScheduleMetadata.from_headers(request.headers)
    ...

A request without a schedule CloudEvent, such as a legacy Cron Job, raises NotAScheduleInvocationError. A path is public, so check authorization: Bearer <CRON_SECRET> as you would for a Cron Job.

Manage schedules

A schedule fires on a cron cadence or once at a fixed time, and publishes to a Vercel Queue topic. It is identified by its name within a namespace, which defaults to "default".

from datetime import timedelta
from vercel.schedules import Cron, create_schedule, query_schedules

schedule = await create_schedule(
    "cleanup",
    topic="scheduled-cleanup",
    cron=Cron(hour=3),  # every day at 03:00
    jitter=timedelta(minutes=2),
    payload={"max_age_days": 30},
)

async for schedule in query_schedules():
    print(schedule.name, schedule.expression, schedule.is_active)

cron= takes a Cron or a crontab string such as "0 3 * * *". Fields you leave out of a Cron default to *, except fields less significant than every field you set, which default to their minimum, as in APScheduler's CronTrigger. Cron(hour=3) is 0 3 * * *, and Cron(day=1) is 0 0 1 * *. str(cron) renders the crontab expression, and Cron.from_crontab() parses one.

jitter spreads each firing over a random delay of 1 to 15 whole minutes.

Timezones

Cron expressions are evaluated in UTC unless you pass an IANA timezone:

await create_schedule(
    "daily-report",
    topic="send-report",
    cron=Cron(hour=9),
    timezone="America/Los_Angeles",
)

Pass at= instead of cron= for a schedule that fires once. An aware datetime carrying a ZoneInfo (or UTC) supplies the timezone itself. A naive datetime needs an explicit timezone=:

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

await create_schedule(
    "launch",
    topic="launch",
    at=datetime(2026, 9, 16, 9, tzinfo=ZoneInfo("America/Los_Angeles")),
)

await create_schedule(
    "follow-up",
    topic="send-report",
    at=datetime.now(timezone.utc) + timedelta(hours=1),
)

Given both an aware at and timezone, at is converted into that timezone, so the instant is preserved. One-off schedules have minute precision: a time with seconds is rounded up to the next minute, so the schedule never fires before at. Fixed-offset datetimes other than UTC are rejected because they carry no IANA name.

Change, pause, and run schedules

get_schedule, update_schedule, enable_schedule, disable_schedule, invoke_schedule, and delete_schedule take the schedule name and an optional namespace=. A missing schedule raises ScheduleNotFoundError, which is also a LookupError.

from datetime import datetime, timezone
from vercel.schedules import enable_schedule, invoke_schedule, update_schedule

await update_schedule("cleanup", cron="0 2 * * *", jitter=None)  # jitter=None clears it
await invoke_schedule("cleanup")  # fire now, outside the cadence
await enable_schedule("cleanup", until=datetime(2026, 12, 1, tzinfo=timezone.utc))

Schedules declared in vercel.json can only be enabled or disabled through the API. Other API errors raise SchedulesApiError, whose code names the reason, such as "schedule_already_exists", and whose retry_after holds the seconds to wait after "rate_limited".

The same surface is available synchronously, with identical names and arguments:

from vercel.schedules.sync import create_schedule, query_schedules

schedule = create_schedule("cleanup", topic="scheduled-cleanup", cron="0 * * * *")
for schedule in query_schedules():
    ...

Configuration

Requests authenticate with the deployment's Vercel OIDC token and target the public Schedules service, overridable with VERCEL_SCHEDULE_BASE_URL. Override either per session:

from vercel.api import session
from vercel.schedules import SchedulesServiceOptions, get_schedule, static_credentials_factory

options = SchedulesServiceOptions(
    base_url="...",
    credentials_factory=static_credentials_factory("..."),
)
async with session(service_options=[options]):
    schedule = await get_schedule("cleanup")

credentials_factory runs before each request, so it can return a refreshed token. For sync calls, use SchedulesServiceOptions from vercel.schedules.sync in a plain with block. Its credentials_factory is a plain function, which may block. Mixing an async call into a sync session, or the reverse, is rejected.

Under vercel dev, the SDK uses the local Schedules API that vercel dev serves, with the token it provides. Elsewhere, run vercel link and vercel env pull so an OIDC token is available, or pass a credentials_factory.

Read the firing in a schedule command

A schedule with run builds the image from the Dockerfile in root, and runs the command once per firing:

{
  "schedules": {
    "reindex": {
      "schedule": "0 3 * * *",
      "root": "jobs",
      "entrypoint": "Dockerfile",
      "run": ["python", "reindex.py"]
    }
  }
}

The firing's metadata is in VERCEL_SCHEDULE_* environment variables. ScheduleMetadata.from_env() reads them:

# jobs/reindex.py
from vercel.schedules import ScheduleMetadata

metadata = ScheduleMetadata.from_env()
print(f"Running {metadata.name}, scheduled at {metadata.scheduled_at}")

A non-zero exit status marks the firing as failed. Failed firings are not retried.

Run by hand, without the variables, from_env() raises NotAScheduleInvocationError. The package is optional here: os.environ["VERCEL_SCHEDULE_NAME"] works too.

Variable ScheduleMetadata attribute
VERCEL_SCHEDULE_ID schedule_id
VERCEL_SCHEDULE_EXECUTION_ID execution_id
VERCEL_SCHEDULE_NAME name
VERCEL_SCHEDULE_NAMESPACE namespace
VERCEL_SCHEDULE_SCHEDULED_AT scheduled_at, as an aware UTC datetime
VERCEL_SCHEDULE_SOURCE source
VERCEL_SCHEDULE_EXPRESSION expression

Metadata

Release files for vercel-schedules 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vercel-schedules 0.1.0
File Size Uploaded Provenance Actions
vercel_schedules-0.1.0.tar.gz 29.4 kB Without provenance Details for vercel_schedules-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vercel-schedules 0.1.0
File Interpreter ABI Platform Actions
vercel_schedules-0.1.0-py3-none-any.whl Python 3 none any Details for vercel_schedules-0.1.0-py3-none-any.whl

Total release size: 65.2 kB

Release files / vercel_schedules-0.1.0.tar.gz

Download URL vercel_schedules-0.1.0.tar.gz
Size 29.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8830c10f85076d58b5a938a101aa93c32c433530766fc5f677d6ccac1f74b3c5
BLAKE2b-256 checksum
How to use checksums
b062aa50641ac3467da9c6a3a9c798f299cd2796cfccca501806c5481f4cce97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / vercel_schedules-0.1.0-py3-none-any.whl

Download URL vercel_schedules-0.1.0-py3-none-any.whl
Size 35.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2bae1a8cb3f5d754f0d88eea028f72643838457d871415bca47cdb87e2c6e870
BLAKE2b-256 checksum
How to use checksums
e2b3ccf6a51a78152b3ae66948b2c607be117825a3934395e74ee7eb1a33677c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for vercel-schedules 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page