Usage | Admin | WP-CLI | Background Processing at Scale | API | FAQ

action-scheduler

A scalable, traceable job queue for background processing large queues of tasks in WordPress. Designed for distribution in WordPress plugins - no server access required.

API Reference

Action Scheduler provides a range of functions for scheduling hooks to run at some time in the future on one or more occassions.

To understand the scheduling functoins, it can help to think of them as extensions to WordPress’ do_action() function that add the ability to delay and repeat when the hook will be triggered.

WP-Cron APIs vs. Action Scheduler APIs

The Action Scheduler API functions are designed to mirror the WordPress WP-Cron API functions.

Functions return similar values and accept similar arguments to their WP-Cron counterparts. The notable differences are:

API Function Availability

As mentioned in the Usage - Load Order section, Action Scheduler will initialize itself on the 'init' hook with priority 1. While API functions are loaded prior to this and call be called, they should not be called until after 'init' with priority 1, because each component, like the data store, has not yet been initialized.

Do not use Action Scheduler API functions prior to 'init' hook with priority 1. Doing so could lead to unexpected results, like data being stored in the incorrect location.

Function Reference / as_schedule_single_action()

Description

Schedule an action to run one time.

Usage

as_schedule_single_action( $timestamp, $hook, $args, $group )

Parameters

Return value

(integer) the action’s ID in the posts table.

Function Reference / as_schedule_recurring_action()

Description

Schedule an action to run repeatedly with a specified interval in seconds.

Usage

as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args, $group )

Parameters

Return value

(integer) the action’s ID in the posts table.

Function Reference / as_schedule_cron_action()

Description

Schedule an action that recurs on a cron-like schedule.

Usage

as_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group )

Parameters

Return value

(integer) the action’s ID in the posts table.

Function Reference / as_unschedule_action()

Description

Cancel the next occurrence of a job.

Usage

as_unschedule_action( $hook, $args, $group )

Parameters

Return value

(null)

Function Reference / as_next_scheduled_action()

Description

Returns the next timestamp for a scheduled action.

Usage

as_next_scheduled_action( $hook, $args, $group )

Parameters

Return value

(integer boolean) The timestamp for the next occurrence, or false if nothing was found.

Function Reference / as_get_scheduled_actions()

Description

Find scheduled actions.

Usage

as_get_scheduled_actions( $args, $return_format )

Parameters

Return value

(array) Array of the actions matching the criteria specified with $args.