Schedules

Schedules start Actors or tasks on a recurring basis using cron expressions. All endpoints are prefixed with https://api.scrape.ly/v2. Authenticate with Authorization: Bearer $SCRAPELY_TOKEN.

Creating, updating, and deleting schedules needs an API key: the Default key, a full-access key, or a scoped key with schedules:write, actors:run, and the run permission actor-default (see API keys & permissions). Actor run tokens receive 403 insufficient-permissions. Reading schedules and their logs needs schedules:read on a scoped key.

There is no endpoint to trigger a schedule manually. To run its Actor or task now, use the Actors API or Tasks API, or Run now on the automation with the same ID.

Schedules are automations

Every schedule is an automation with a schedule trigger, and the same ID works in both APIs. /v2/schedules is a view of your automations in the shape existing schedule clients expect:

• It lists only automations with a schedule trigger. Automations that run manually or after another run finishes are not listed here, and GET, PUT, DELETE, and /log on them return 404. Use the Automations API for those.
• An automation's filters, AI step, and deliveries appear under one extra key, automation, which is only present when it has any of them. It never contains secrets:

"automation": {
  "hasAiStep": true,
  "filters": { "onlyWithResults": false, "onlyNewItems": { "keyFields": ["url"] }, "conditions": [] },
  "deliveries": [ { "channel": "email" }, { "channel": "webhook" } ]
}

• A PUT changes only the fields you send. Replacing actions replaces the run steps and keeps the automation's AI step, filters, and deliveries. To change those, use Update automation.
• DELETE also deletes the automation's run history.
• notificationsEnabled is the automation's failure alert (options.notifyOnFailure in the Automations API). Both read and change the same setting.

Endpoints

Errors and limits

Get list of schedules

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  "https://api.scrape.ly/v2/schedules?search=daily&sortBy=nextRunAt&desc=1&limit=20"

nextRunAt is null while the schedule is disabled.

Create schedule

curl -X POST https://api.scrape.ly/v2/schedules \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-scrape",
    "cronExpression": "0 6 * * *",
    "actions": [
      { "type": "RUN_ACTOR_TASK", "actorTaskId": "kQ7mN2pXv9LsT4wRb" }
    ]
  }'

Returns 201 with { "data": { ...schedule } }. Actions in the response are normalized.

Actions

Each action is RUN_ACTOR or RUN_ACTOR_TASK; a missing type means RUN_ACTOR. A schedule can have at most 10 actions of each type, and every scheduled Actor must have at least one successful build. All actions start together each time the schedule fires.

When a scheduled run starts, each setting falls back in order:

• Input: for a RUN_ACTOR action, the action's runInput, then your default saved input for the Actor, then the prefill and default values from the Actor's input schema. For a RUN_ACTOR_TASK action, the task's input as it is when the schedule fires, with the action's runInput merged over it one level deep: top-level fields in runInput replace the task's, the other fields stay as saved. To change a nested value, send the whole top-level field.
• Options: the action's runOptions, then the task's options, then the Actor's defaults, then build latest, a 3,600-second timeout, and 2,048 MB of memory. maxTotalChargeUsd falls back to the Actor's minimum.

Scheduled runs have origin set to SCHEDULER.

Responses normalize actions and give each one a 9-character id:

• RUN_ACTOR_TASK returns id, actorTaskId, taskName (when known), and the stored input as input. runOptions is not returned but is still used.
• RUN_ACTOR returns id, actorId, actorName (when known), runInput, and runOptions.

A RUN_ACTOR action on create:

{
  "type": "RUN_ACTOR",
  "actorId": "eLN5rTB8sYTBWdfzx",
  "runInput": { "body": "{\"startUrls\":[{\"url\":\"https://example.com\"}]}", "contentType": "application/json" },
  "runOptions": { "memoryMbytes": 2048, "timeoutSecs": 3600 }
}

Cron expressions

cronExpression has five space-separated fields, evaluated in the schedule's timezone:

Each field can be *, a number (5), a range (1-5), a list (1,15,30 or 1-5,10), or a step: */15, 1-30/5, or 5/15 (from 5 to the end of the range, every 15). Names are case-insensitive. ? means the same as * in the day fields.

Instead of the five fields, you can use a macro:

The rules follow standard (Vixie) cron:

• When both day of month and day of week are restricted, a day matches if either matches. 0 9 1 * MON fires on the 1st of the month and on every Monday.
• Daylight saving: a schedule with a fixed minute and hour fires once when the clock falls back, on the first occurrence of that time. If the clock springs forward over that time, it fires right after the jump. Schedules with * or a step in the minute or hour field follow elapsed time, so they have no runs in the skipped hour and run again in the repeated hour.

The scheduler checks for due schedules once a minute, so runs start up to about a minute after the scheduled time. Times missed while the scheduler was down are skipped, not caught up.

Get schedule

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/schedules/9d4b2f6e-7a1c-4e3b-8f5d-2c0a1b9e7d3f

Returns { "data": { ...schedule } } with normalized actions.

Update schedule

Send only the fields you want to change; the fields are the same as Create schedule. actions, if sent, replaces the whole list, and the action limits and build check apply to the new list. nextRunAt is recalculated.

curl -X PUT https://api.scrape.ly/v2/schedules/9d4b2f6e-7a1c-4e3b-8f5d-2c0a1b9e7d3f \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isEnabled": false,
    "cronExpression": "0 7 * * *"
  }'

Returns the updated schedule.

Delete schedule

Returns 204 No Content.

curl -X DELETE -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/schedules/9d4b2f6e-7a1c-4e3b-8f5d-2c0a1b9e7d3f

Get schedule log

Returns JSON { "data": [...] }, not plain text. Each entry is one firing of the schedule, oldest first. The newest 30 firings are kept.

Messages take these forms:

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/schedules/9d4b2f6e-7a1c-4e3b-8f5d-2c0a1b9e7d3f/log