This document covers the public query helpers for scheduled actions.

Overview

Action Scheduler provides three main query helpers:

• as_next_scheduled_action() — find the next scheduled occurrence for a hook/args/group.
• as_has_scheduled_action() — fast boolean check for pending or running actions.
• as_get_scheduled_actions() — detailed query with pagination, filtering, and return formats.

as_next_scheduled_action()

Check if there is an existing action in the queue with a given hook, args, and group combination.

Signature

as_next_scheduled_action( string $hook, ?array $args = null, string $group = '' ): int|bool

Parameters

• $hook (string) — Hook name to search for.
• $args (array|null) — Args to match. When null, args are ignored for matching. When an array, must match exactly.
• $group (string) — Group name to match.

Returns

• int — Unix timestamp for the next pending scheduled action.
• true — A matching action is running or is a pending async action with a null schedule.
• false — No matching pending or running action exists.

Behavior

• Checks for running actions first. If found, returns true.
• Then checks for pending actions. If found, returns the scheduled timestamp.
• If the pending action has a null schedule (async), returns true.

Example

$next = as_next_scheduled_action(
    'myplugin_send_report',
    array( 'report_id' => 99 ),
    'myplugin'
);

if ( false === $next ) {
    // No matching action scheduled.
} elseif ( true === $next ) {
    // Running now or async action queued.
} else {
    // Timestamp for next scheduled run.
    $date = gmdate( 'Y-m-d H:i:s', $next );
}

Edge cases

• If Action Scheduler is not initialized, returns false.
• When $args is not an array (and not null), it is ignored for matching.
• A pending async action (null schedule) returns true, not a timestamp.

as_has_scheduled_action()

Efficiently check whether a specific action is currently scheduled (pending or in-progress).

Signature

as_has_scheduled_action( string $hook, ?array $args = null, string $group = '' ): bool

Parameters

• $hook (string) — Hook name to search for.
• $args (array|null) — Args to match. When null, args are ignored for matching.
• $group (string) — Group name to match.

Returns

• bool — true if a matching action is pending or running; otherwise false.

Example

if ( ! as_has_scheduled_action( 'myplugin_sync_catalog', null, 'myplugin' ) ) {
    as_schedule_single_action( time() + 60, 'myplugin_sync_catalog', array(), 'myplugin' );
}

Edge cases

• If Action Scheduler is not initialized, returns false.
• When $args is null, it matches any args for the given hook/group.

as_get_scheduled_actions()

Find scheduled actions with a detailed query and optional return formats.

Signature

as_get_scheduled_actions( array $args = array(), string $return_format = OBJECT ): array

Parameters

• $args (array) — Query parameters (see below).
• $return_format (string) — OBJECT (default), ARRAY_A, or ids/int.

Query parameters

Returns

• array —
  • When $return_format is OBJECT (default), returns an array of Action objects keyed by action ID.
  • When $return_format is ARRAY_A, returns arrays of object properties keyed by action ID.
  • When $return_format is ids or int, returns an array of action IDs.

Example

// Fetch the next 10 pending actions for a hook.
$actions = as_get_scheduled_actions(
    array(
        'hook'   => 'myplugin_send_report',
        'status' => ActionScheduler_Store::STATUS_PENDING,
        'per_page' => 10,
        'orderby'  => 'date',
        'order'    => 'ASC',
    )
);

foreach ( $actions as $action_id => $action ) {
    $date = $action->get_schedule()->get_date();
}

Edge cases

• If Action Scheduler is not initialized, returns an empty array.
• date and modified values are normalized to ActionScheduler_DateTime internally using as_get_datetime_object().
• status may be a single string or an array of statuses.
• orderby set to none skips ordering, which can improve performance for existence checks.