Edit

Schedules

Learn how to automatically start your actor and task runs and the basics of *cron* expressions. Set up and manage your schedules from the Apify app or via API.

Schedules allow you to run your actors and tasks at specific times. You schedule the run frequency using cron expressions.

Schedules allow timezone settings and support daylight saving time shifts (DST).

You can set up and manage schedules both from the Apify app and via API. When scheduling a new actor or task run, you can override its input settings using a JSON object similarly to when invoking a schedule using the Apify API.

In most cases, scheduled events are fired within one second of their scheduled time.
Occasionally, however, runs can be delayed because of a system overload or a server shutting down.

Each schedule can be associated with a maximum of 10 actors and 10 actor tasks.

Setting up a new schedule

Before setting up a new schedule, you should have the actor or task whose run you want to schedule prepared and tested.

If you are planning to schedule an actor run, you need to use the actor before you can schedule any runs. Navigate to the actor's page in the Apify Store, click the Try for free button, then Save & run it with your preferred settings.

From the Apify app

In the Apify app, click on the Schedules button in the left side menu, then click the Create new button.

In the Settings tab, give your schedule a memorable name, add a description, and choose how often you would like your actor or task to run using the Cron expression field.

New schedule

Next, you'll need to give the schedule something to run. This is where the actor or task you prepared earlier comes in. Switch to the Actors or Tasks tab, as appropriate, and click the Add actor/task button.

If you're scheduling an actor run, you'll be able to specify the build, timeout, memory, and body. The timeout value is specified in seconds; a value of 0 means there is no timeout and the actor runs until it finishes. The body should contain a JSON object with the actor's input.

Add actor to schedule

If you're scheduling a task, just select the task you prepared earlier from the Task dropdown. If you need to override the task's input, you can pass it as a JSON object in the Input JSON overrides field.

Add task to schedule

To add more actors or tasks, just repeat the process.

You can add a maximum of 10 actors and 10 tasks to each schedule.

Now, all you need to do is click Save and wait for your scheduled actors/tasks to run and return your data.

If you are an advanced user, you can also add a webhook to your tasks, which will notify you (or perform an action of your choice) every time the task runs.

Via API

To create a new schedule using the Apify API, send a POST request to

https://api.apify.com/v2/schedules?token={your_API_token}

You can find your secret API token in your Apify account's Integrations tab. In the POST request's payload should be a JSON object specifying the schedule's name, your user ID, and the schedule's actions.

The below JSON object creates a schedule which runs an SEO audit of the Apify domain once a month.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "name": "apify-domain-monthly-seo-audit",
  "userId": "7AxwNO4kCDZxsMHip",
  "isEnabled": true,
  "isExclusive": true,
  "cronExpression": "@monthly",
  "timezone": "UTC",
  "description": "A monthly audit of the Apify domain's SEO",
  "actions": [
    {
      "type": "RUN_ACTOR_TASK",
      "actorTaskId": "6rHoK2zjYJkmYhSug",
      "input": {
        "startUrl": "https://apify.com"
      }
    }
  ]
}

If the request is successful, you will receive a 201 HTTP response code and a JSON object in the response body containing the details of your new schedue. If you receive an error (4** code), you will need to check your API token, user ID, or POST request body.

You can add multiple actor and task runs to a schedule with a single POST request. Simply add another object with the run's details to the actions array in your POST request's payload object.

For more information, see the schedules section in the API documentation.

Cron expressions

Schedules use cron expressions to specify run times. A cron expression has the following structure:

Position Field Values Wildcards Optional
1 second 0 - 59 , - * / yes
2 minute 0 - 59 , - * / no
3 hour 0 - 23 , - * / no
4 day of month 1 - 31 , - * / no
5 month 1 - 12 , - * / no
6 day of week 0 - 7 (0 or 7 is Sunday) , - * / no

For example, the expression 30 5 16 * * 1 will start an actor at 16:05:30 every Monday.

The minimum interval between runs is 10 seconds; if your next run is scheduled sooner than 10 seconds after the previous run, the next run will be skipped.

Examples of cron expressions

  • 0 8 * * * - every day at 8am.
  • 0 0 * * 0 - every 7 days (at 00:00 on Sunday).
  • */3 * * * * - every 3rd minute.
  • 0 0 1 */2 * - every other month (at 00:00 on the first day of month, every 2nd month).

Additionally, you can use the following shortcut expressions:

  • @yearly = 0 0 1 1 * - once a year, on Jan 1st at midnight.
  • @monthly = 0 0 1 * * - once a month, on the 1st at midnight.
  • @weekly = 0 0 * * 0 - once a week, on Sunday at midnight.
  • @daily = 0 0 * * * - run once a day, at midnight.
  • @hourly = 0 * * * * - on the hour, every hour.

You can find more information and examples of cron expressions on crontab.guru. For additional and non-standard characters, see this Wikipedia article.

Sharing

You can invite other Apify users to view or modify your schedules using the access rights system. See the full list of permissions here.