---
title: "Scheduler API"
manual: "Scheduler"
version: "main"
permalink: "https://docs.typo3.org/permalink/typo3/cms-scheduler:scheduler-api@main"
source: "DevelopersGuide/SchedulerApi/Index.rst"
rendered: "2026-10-08T06:49:14+00:00"
---

# Scheduler API {#scheduler-api}

It is possible to refer to the Scheduler from other extensions. Once a
`\TYPO3\CMS\Scheduler\Scheduler` object has been instantiated all of its
public methods can be used. The PHPdoc of the methods should be enough to
understand what each is to be used for.

The extension ships with a
`\TYPO3\CMS\Scheduler\Domain\Repository\SchedulerTaskRepository` class,
which provides some helpful methods, for example:

-   `findByUid(int $uid)`: this method is used to fetch a registered task
    from the database given an ID. It throws an `\OutOfBoundsException`
    if no task with this ID exists.
-   `findNextExecutableTask()`: this method returns the next due task. The
    return value is the unserialized task object, or `null` if no task is due.
-   `findRecordByUid(int $uid)`: is also used to retrieve a registered task
    from the database, but it returns the record corresponding to the task
    registration and not the task object itself.

These are the main methods that will be used from outside the
Scheduler as they can retrieve registered tasks from the database.
When a task has been fetched, all public methods from the
`\TYPO3\CMS\Scheduler\Task\AbstractTask` class can be used.

## Invalid tasks {#scheduler-api-invalid-task}

<!-- TODO: no Markdown rendering for "versionchanged" -->

Before, the methods threw an \UnexpectedValueException.

If a task cannot be deserialized or is otherwise invalid, `findByUid()`
and `findNextExecutableTask()` throw an
`\TYPO3\CMS\Scheduler\Exception\InvalidTaskException`. The
Scheduler also disables the task, so that it is not selected for execution
again.

```php
use TYPO3\CMS\Scheduler\Exception\InvalidTaskException;

try {
  $task = $schedulerTaskRepository->findByUid($taskUid);
} catch (InvalidTaskException) {
  // Handle the invalid task.
}
```