Title: wp_get_scheduled_event
Published: February 22, 2019
Last modified: February 24, 2026

---

# wp_get_scheduled_event( string $hook, array $args = array(), int|null $timestamp = null ): object|false

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#wp--skip-link--target)

Retrieves a scheduled event.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#description)󠁿

Retrieves the full event object for a given event, if no timestamp is specified 
the next scheduled event is returned.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#parameters)󠁿

 `$hook`stringrequired

Action hook of the event.

`$args`arrayoptional

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:`array()`

`$timestamp`int|nulloptional

Unix timestamp (UTC) of the event. If not specified, the next scheduled event is
returned.

Default:`null`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#return)󠁿

 object|false The event object. False if the event does not exist.

 * `hook` string
 * Action hook to execute when the event is run.
 * `timestamp` int
 * Unix timestamp (UTC) for when to next run the event.
 * `schedule` string|false
 * How often the event should subsequently recur.
 * `args` array
 * Array containing each separate argument to pass to the hook’s callback function.
 * `interval` int
 * Optional. The interval time in seconds for the schedule. Only present for recurring
   events.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#source)󠁿

    ```php
    function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
    	/**
    	 * Filter to override retrieving a scheduled event.
    	 *
    	 * Returning a non-null value will short-circuit the normal process,
    	 * returning the filtered value instead.
    	 *
    	 * Return false if the event does not exist, otherwise an event object
    	 * should be returned.
    	 *
    	 * @since 5.1.0
    	 *
    	 * @param null|false|object $pre  Value to return instead. Default null to continue retrieving the event.
    	 * @param string            $hook Action hook of the event.
    	 * @param array             $args 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.
    	 * @param int|null  $timestamp Unix timestamp (UTC) of the event. Null to retrieve next scheduled event.
    	 */
    	$pre = apply_filters( 'pre_get_scheduled_event', null, $hook, $args, $timestamp );

    	if ( null !== $pre ) {
    		return $pre;
    	}

    	if ( null !== $timestamp && ! is_numeric( $timestamp ) ) {
    		return false;
    	}

    	$crons = _get_cron_array();
    	if ( empty( $crons ) ) {
    		return false;
    	}

    	$key = md5( serialize( $args ) );

    	if ( ! $timestamp ) {
    		// Get next event.
    		$next = false;
    		foreach ( $crons as $timestamp => $cron ) {
    			if ( isset( $cron[ $hook ][ $key ] ) ) {
    				$next = $timestamp;
    				break;
    			}
    		}

    		if ( ! $next ) {
    			return false;
    		}

    		$timestamp = $next;
    	} elseif ( ! isset( $crons[ $timestamp ][ $hook ][ $key ] ) ) {
    		return false;
    	}

    	$event = (object) array(
    		'hook'      => $hook,
    		'timestamp' => $timestamp,
    		'schedule'  => $crons[ $timestamp ][ $hook ][ $key ]['schedule'],
    		'args'      => $args,
    	);

    	if ( isset( $crons[ $timestamp ][ $hook ][ $key ]['interval'] ) ) {
    		$event->interval = $crons[ $timestamp ][ $hook ][ $key ]['interval'];
    	}

    	return $event;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/cron.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/cron.php#L751)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/cron.php#L751-L818)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#hooks)󠁿

 [apply_filters( ‘pre_get_scheduled_event’, null|false|object $pre, string $hook, array $args, int|null $timestamp )](https://developer.wordpress.org/reference/hooks/pre_get_scheduled_event/)

Filter to override retrieving a scheduled event.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#related)󠁿

| Uses | Description | 
| [_get_cron_array()](https://developer.wordpress.org/reference/functions/_get_cron_array/)`wp-includes/cron.php` |

Retrieves cron info array option.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  |

| Used by | Description | 
| [wp_reschedule_event()](https://developer.wordpress.org/reference/functions/wp_reschedule_event/)`wp-includes/cron.php` |

Reschedules a recurring event.

  | 
| [wp_next_scheduled()](https://developer.wordpress.org/reference/functions/wp_next_scheduled/)`wp-includes/cron.php` |

Retrieves the timestamp of the next scheduled event for the given hook.

  | 
| [wp_get_schedule()](https://developer.wordpress.org/reference/functions/wp_get_schedule/)`wp-includes/cron.php` |

Retrieves the name of the recurrence schedule for an event.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#changelog)󠁿

| Version | Description | 
| [5.1.0](https://developer.wordpress.org/reference/since/5.1.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 3 content](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#comment-content-3253)
 2.    [naui95](https://profiles.wordpress.org/naui95/)  [  7 years ago  ](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/#comment-3253)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F%23comment-3253)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F%23comment-3253)
 4.  **$args** is not an optional parameter if looking for events that have _args_.
     The function will return null if no args are given and the scheduled event has
     args.
 5.   [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F%3Freplytocom%3D3253%23feedback-editor-3253)
 6.   [Skip to note 4 content](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/?output_format=md#comment-content-4522)
 7.    [Nawawi Jamili](https://profiles.wordpress.org/nawawijamili/)  [  5 years ago  ](https://developer.wordpress.org/reference/functions/wp_get_scheduled_event/#comment-4522)
 8.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F%23comment-4522)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F%23comment-4522)
 9.  Remove old event without deactivate/activate plugin.
 10.     ```php
         if ( false !== wp_get_scheduled_event( 'old_hook' ) ) {
         	wp_clear_scheduled_hook( 'old_hook' );
         }
         ```
     
 11.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F%3Freplytocom%3D4522%23feedback-editor-4522)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_get_scheduled_event%2F)
before being able to contribute a note or feedback.