wp_next_scheduled( string $hook, array $args = array() )

Retrieve the next timestamp for an event.

Description Description

Parameters Parameters


(string) (Required) Action hook to execute when event is run.


(array) (Optional) Arguments to pass to the hook's callback function.

Default value: array()

Top ↑

Return Return

(false|int) The Unix timestamp of the next time the scheduled event will occur.

Top ↑

Source Source

File: wp-includes/cron.php

function wp_next_scheduled( $hook, $args = array() ) {
	$crons = _get_cron_array();
	$key = md5(serialize($args));
	if ( empty($crons) )
		return false;
	foreach ( $crons as $timestamp => $cron ) {
		if ( isset( $cron[$hook][$key] ) )
			return $timestamp;
	return false;

Top ↑

Changelog Changelog

Version Description
2.1.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note content
    Contributed by ub3rst4r

    Note the $args parameter! Not specifying the $args parameter in wp_next_scheduled but having $args for wp_schedule_event will cause many events to be scheduled (instead of just one).

    Bad Example:

    if ( ! wp_next_scheduled( 'myevent' ) ) { // This will always be false
    	wp_schedule_event( time(), 'daily', 'myevent', array( false ) );

    Good Example:

    $args = array( false );
    if ( ! wp_next_scheduled( 'myevent', $args ) ) {
    	wp_schedule_event( time(), 'daily', 'myevent', $args );
  2. Skip to note content
    Contributed by Kuba Mikita

    Be careful when using arguments! WordPress doesn’t compare them 1:1 so you have to pay attention what type these are.

    It’s because WP generates a hash out of them: md5( serialize( $args ) )

    So when you have:

    wp_schedule_event( time(), 'daily', 'action_hook', array( 123 ) );

    And use a string because ie. the value was taken from the meta:

    wp_next_scheduled( 'action_hook', array( '123' ) );

    It will return false.

You must log in before being able to contribute a note or feedback.