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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.