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

Retrieve the next timestamp for an event.

Description Description

Parameters Parameters


(string) (Required) Action hook of the event.


(array) (Optional) Array containing each separate argument to pass to the hook's callback function. Although not passed to a callback, these arguments are used to uniquely identify the event, so they should be the same as those used when originally scheduling the event.

Default value: array()

Top ↑

Return Return

(false|int) The Unix timestamp of the next time the event will occur. False if the event doesn't exist.

Top ↑

Source Source

File: wp-includes/cron.php

function wp_next_scheduled( $hook, $args = array() ) {
	$next_event = wp_get_scheduled_event( $hook, $args );
	if ( ! $next_event ) {
		return false;

	return $next_event->timestamp;

Top ↑

Changelog Changelog

Version Description
2.1.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 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 2 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.