Edgenivo Schedules: JS SDK Reference

Use the @vercel/schedules package to create and manage dynamic schedules from your code, and to handle runs in a function. To manage schedules from the terminal instead, use vercel schedules. To call the API without the SDK, see the API Reference.

npm i @vercel/schedules

On Edgenivo, the SDK authenticates with your deployment's OIDC token. You don't need to configure anything. Each call applies to the environment or branch of the deployment that runs it:

The package exports a default client, Schedules, that's ready to use:

import { Schedules } from '@vercel/schedules';
 
const schedule = await Schedules.get({ name: 'cleanup' });

To pass options, create your own SchedulesClient. It has the same methods as Schedules:

import { SchedulesClient } from '@vercel/schedules';
 
const schedules = new SchedulesClient({
  token: process.env.VERCEL_OIDC_TOKEN,
});

The default Schedules client reads its configuration when you import the package. If you change environment variables at runtime, create a new SchedulesClient afterward.

Schedules.create() creates a dynamic schedule that publishes to a queue topic. It takes effect immediately.

import { Schedules } from '@vercel/schedules';
 
const schedule = await Schedules.create({
  name: 'cleanup',
  target: { topic: 'scheduled-cleanup' },
  expression: { type: 'cron', cron: '0 * * * *' },
  timezone: 'America/New_York',
  jitter: 5,
  payload: { maxAgeDays: 30 },
});
 
console.log(schedule.scheduleId, schedule.state);

Returns the new Schedule. Throws a SchedulesApiError with code schedule_already_exists if a schedule with the same name exists in the namespace.

Pass { type: 'single', at } to run once at a local date and time. Set timezone separately, or omit it to use UTC:

await Schedules.create({
  name: 'send-reminder',
  target: { topic: 'reminders' },
  expression: { type: 'single', at: '2026-11-01T09:00' },
  timezone: 'America/New_York',
});

The at value uses YYYY-MM-DDTHH:mm format. See One-time expressions for the full format rules.

Schedules.list() returns static and dynamic schedules in one namespace, one page at a time:

const { data, cursor } = await Schedules.list({
  namespace: 'default',
  limit: 50,
});
 
for (const schedule of data) {
  console.log(schedule.name, schedule.state, schedule.target.type);
}

Returns { data: Schedule[], cursor: string | null }. When cursor is null, there are no more pages. To read every page:

let cursor: string | undefined;
 
do {
  const page = await Schedules.list({ namespace: 'default', cursor });
  for (const schedule of page.data) {
    console.log(schedule.name);
  }
  cursor = page.cursor ?? undefined;
} while (cursor);

Static schedules can target a function or a path, so check target.type before you read the target:

import type { Schedule } from '@vercel/schedules';
 
function describeTarget(schedule: Schedule): string {
  switch (schedule.target.type) {
    case 'queue':
      return `topic ${schedule.target.topic}`;
    case 'function':
      return `function ${schedule.target.function}`;
    case 'path':
      return `path ${schedule.target.path}`;
  }
}

Schedules.get() returns one static or dynamic schedule by name:

const schedule = await Schedules.get({ name: 'cleanup' });

Throws a SchedulesApiError with code not_found if the schedule doesn't exist.

Schedules.update() changes a dynamic schedule. Properties you leave out keep their current values:

await Schedules.update({
  name: 'cleanup',
  expression: { type: 'cron', cron: '0 2 * * *' },
  payload: { maxAgeDays: 60 },
});

Returns the updated Schedule. You can't update a static schedule. Edit your configuration and redeploy instead. To change a schedule's expression type, delete it and create it again.

Schedules.enable() and Schedules.disable() change whether a static or dynamic schedule runs on its cadence:

await Schedules.disable({ name: 'cleanup' });
await Schedules.enable({ name: 'cleanup' });

Pass until to enable() to enable the schedule until a set time:

await Schedules.enable({
  name: 'cleanup',
  until: new Date(Date.now() + 2 * 60 * 60 * 1000),
});

Both methods return the updated Schedule. When you pass until:

• The schedule's activeUntil field holds the end time until it passes.
• Calling enable() again with until replaces the end time.
• Calling enable() without until keeps the schedule active indefinitely.
• If the schedule is already active indefinitely, the call fails with code schedule_already_active. Disable it first.

Schedules.invoke() runs a static or dynamic schedule now, without changing its state or cadence:

await Schedules.invoke({ name: 'cleanup' });

The method returns once Edgenivo accepts the run. Your target receives it shortly afterward, the same way as a scheduled run. You can invoke an inactive schedule.

Schedules.delete() deletes a dynamic schedule and stops its future runs:

await Schedules.delete({ name: 'cleanup' });

You can't delete a static schedule. Remove it from your configuration and redeploy instead.

After you delete a schedule, you can create a new one with the same name right away. You can delete a one-time schedule before it runs or after its run is dispatched, but not while the run is being dispatched. See Delete a schedule.

The package also exports helpers for functions that a schedule targets:

import { handleSchedule } from '@vercel/schedules';
 
export const POST = handleSchedule(async (metadata, request) => {
  console.log(`${metadata.name} run ${metadata.executionId}`);
  await deleteExpiredRecords();
});

See Handling scheduled runs for function, path, and queue examples.

Failed API calls throw a SchedulesApiError:

Common codes:

import { Schedules, SchedulesApiError } from '@vercel/schedules';
 
async function findSchedule(name: string) {
  try {
    return await Schedules.get({ name });
  } catch (error) {
    if (error instanceof SchedulesApiError && error.code === 'not_found') {
      return null;
    }
    throw error;
  }
}

create(), get(), list(), update(), enable(), and disable() return Schedule objects:

target has one of these shapes:

handleSchedule and parseScheduleEvent return ScheduleMetadata:

A schedule with a queue target publishes a ScheduleQueueMessage to its topic each time it runs. Pass your payload's type as the parameter:

import { handleCallback } from '@vercel/queue';
import type { ScheduleQueueMessage } from '@vercel/schedules';
 
export const POST = handleCallback<ScheduleQueueMessage<{ reportType: string }>>(
  async (message) => {
    await generateReport(message.payload?.reportType ?? 'summary');
  },
);

• Handling scheduled runs
• Multi-tenant schedules
• vercel schedules reference