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

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 occasions.

To understand the scheduling functions, 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 can 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. To make this easier:

Function Reference / as_enqueue_async_action()

Description

Enqueue an action to run one time, as soon as possible.

Usage

as_enqueue_async_action( $hook, $args, $group, $unique, $priority );

Parameters

Return value

(integer) the action’s ID. Zero if there was an error scheduling the action. The error will be sent to error_log.

Function Reference / as_schedule_single_action()

Description

Schedule an action to run one time at some defined point in the future.

Usage

as_schedule_single_action( $timestamp, $hook, $args, $group, $unique, $priority );

Parameters

Return value

(integer) the action’s ID. Zero if there was an error scheduling the action. The error will be sent to error_log.

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, $unique, $priority );

Parameters

Return value

(integer) the action’s ID. Zero if there was an error scheduling the action. The error will be sent to error_log.

Function Reference / as_schedule_cron_action()

Description

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

If execution of a cron-like action is delayed, the next attempt will still be scheduled according to the provided cron expression.

Usage

as_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group, $unique, $priority );

Parameters

Return value

(integer) the action’s ID. Zero if there was an error scheduling the action. The error will be sent to error_log.

Function Reference / as_unschedule_action()

Description

Cancel the next occurrence of a scheduled action.

Usage

as_unschedule_action( $hook, $args, $group );

Parameters

Return value

(null)

Function Reference / as_unschedule_all_actions()

Description

Cancel all occurrences of a scheduled action.

Usage

as_unschedule_all_actions( $hook, $args, $group )

Parameters

Return value

(string|null) The scheduled action ID if a scheduled action was found, or null if no matching action found.

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 of a pending scheduled action, true for an async or in-progress action or false if there is no matching action.

Function Reference / as_has_scheduled_action()

Description

Check if there is a scheduled action in the queue, but more efficiently than as_next_scheduled_action(). It’s recommended to use this function when you need to know whether a specific action is currently scheduled. Available since 3.3.0.

Usage

as_has_scheduled_action( $hook, $args, $group );

Parameters

Return value

(boolean) True if a matching action is pending or in-progress, false otherwise.

Function Reference / as_get_scheduled_actions()

Description

Find scheduled actions.

Usage

as_get_scheduled_actions( $args, $return_format );

Parameters

Return value

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