Actor tasks

A task is a saved configuration for an Actor: a name, an input object, and run options. The dashboard calls tasks saved inputs (see Saved inputs); they are the same objects. All paths are relative to https://api.scrape.ly. Authentication is required, except for the public example-task endpoints. You can only access your own tasks.

Task responses use actId for the Actor ID (the create body also accepts actorId).

{taskId} can be the task ID, username~task-name, or ~task-name for one of your own tasks.

List tasks

Each item includes the Actor name and icon, totalRuns, and lastRun.

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  "https://api.scrape.ly/v2/actor-tasks?limit=20&desc=1"

List tasks for an Actor

Returns your tasks for that Actor, even if you don't own the Actor (it must be public or yours). Default limit is 20; desc defaults to newest first.

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  "https://api.scrape.ly/v2/actors/eLN5rTB8sYTBWdfzx/tasks"

Saved inputs for an Actor

saved-inputs returns what the dashboard's Input dropdown shows, in one call: your tasks for the Actor (default first, then most recently used, each with totalRuns, lastRun and the automations that use it), the Actor's examples with their input (secret fields masked), and your last three runs of the Actor. input-presets is public and returns only the examples.

examples lists the published example tasks first (id e:<slug>, source: "example"), then the presets the owner marked in the Actor's scenarios (id s:<scenario name>, source: "scenario", with slug, order, and reliability). reliability is ok, degraded (the latest automatic test cycle confirmed a failure; the dashboard shows May be unreliable), or untested. Hidden presets, and entries with the same input as an earlier one, are left out. Use the id in a link: ?input=s:<scenario name> on the Actor's page selects that entry.

{
  "data": {
    "savedInputs": [
      { "id": "tAsKiDeXaMpLe123", "name": "maps-dentists-austin", "title": "Dentists in Austin", "isDefault": true,
        "lastUsedAt": "2026-08-20T09:00:00.000Z", "modifiedAt": "2026-08-14T15:00:00.000Z", "totalRuns": 12,
        "lastRun": { "id": "rUnIdExAmPlE1234", "status": "SUCCEEDED", "startedAt": "2026-08-20T09:00:00.000Z" },
        "automations": [] }
    ],
    "examples": [
      { "id": "e:restaurants-berlin", "source": "example", "title": "Restaurants in Berlin, 20 places", "description": "…", "input": { "searchTerms": ["restaurant"] }, "reliability": null },
      { "id": "s:search-dentists", "source": "scenario", "slug": "search-dentists", "title": "Dentists in Austin, 10 places", "description": null, "input": { "searchTerms": ["dentist"], "location": "Austin" }, "order": 1, "reliability": "ok" }
    ],
    "recentRuns": [ { "id": "rUnIdExAmPlE1234", "status": "SUCCEEDED", "startedAt": "2026-08-20T09:00:00.000Z", "taskId": "tAsKiDeXaMpLe123" } ]
  }
}

Create task

The Actor must be public or yours, and must have at least one successful build. Task names are unique per user and at most 30 characters. Input is limited to 9 MB. Returns 201 and a Location header.

curl -X POST https://api.scrape.ly/v2/actor-tasks \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actId": "eLN5rTB8sYTBWdfzx",
    "name": "daily-scrape",
    "title": "Daily scrape",
    "input": { "url": "https://example.com" },
    "options": { "memoryMbytes": 2048, "timeoutSecs": 3600 }
  }'

Get task

{
  "data": {
    "id": "tAsKiDeXaMpLe123",
    "userId": "uSeRiDeXaMpLe123",
    "actId": "eLN5rTB8sYTBWdfzx",
    "name": "daily-scrape",
    "title": "Daily scrape",
    "input": { "url": "https://example.com" },
    "options": { "memoryMbytes": 2048, "timeoutSecs": 3600 },
    "createdAt": "2026-08-14T15:00:00.000Z",
    "modifiedAt": "2026-08-14T15:00:00.000Z",
    "stats": { "totalRuns": 12 },
    "isPublic": false,
    "publicSlug": null,
    "seoTitle": null,
    "seoDescription": null,
    "useCase": null,
    "publishedAt": null,
    "isDefault": true,
    "lastUsedAt": "2026-08-20T09:00:00Z"
  }
}

isDefault and lastUsedAt (when a run of the task last started, or null) are Scrape.ly additions; list items carry them too, plus title.

Update task

Send any of name, title, input, options, seoTitle, seoDescription, and isDefault. The same name and memory rules as create apply.

While a task is published, its input cannot change: an input edit returns 409 task-published-input-immutable. Unpublish the task, edit it, then publish it again.

curl -X PUT https://api.scrape.ly/v2/actor-tasks/tAsKiDeXaMpLe123 \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Nightly scrape", "input": { "url": "https://example.com/v2" }}'

Delete task

Returns 204 No Content.

curl -X DELETE https://api.scrape.ly/v2/actor-tasks/tAsKiDeXaMpLe123 \
  -H "Authorization: Bearer $SCRAPELY_TOKEN"

Task input

GET returns the saved input as raw JSON, not wrapped in data ({} if there is none). PUT replaces it; the body is the input object (9 MB limit, else 400 input-too-large). The response is the stored input object.

curl -X PUT https://api.scrape.ly/v2/actor-tasks/tAsKiDeXaMpLe123/input \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "maxResults": 100}'

List task runs

Each run item also carries taskName.

Run task

Starts a run with the task's saved input. A non-empty JSON body is merged over the saved input, field by field at the top level (send input fields, not { "input": ... }). A webhooks key in the body is read as ad-hoc webhooks and is not added to the input.

Returns 201 with the run object and a Location header.

Unset options fall back to the task's options, then the Actor's defaults, then latest, 2048 MB, and 3600 seconds.

curl -X POST "https://api.scrape.ly/v2/actor-tasks/tAsKiDeXaMpLe123/runs?waitForFinish=30" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxResults": 20}'

Starting a task run can fail with the same errors as Start a run, including 429 concurrency-limit-exceeded and 403 full-permission-actor-not-approved (see Permission approvals).

To make retries safe, send an Idempotency-Key header (or the idempotencyKey query parameter). A repeat with the same key returns 201 with the original run at once and ignores waitForFinish. While the first request is still starting the run, a repeat gets 409 idempotency-key-in-progress; a key already used for a different request returns 422 idempotency-key-reused. See Idempotent run starts.

Run task synchronously

Starts a task run and waits for it to finish. On success, returns the OUTPUT key-value record as raw JSON with status 201, not the run object and not a data envelope.

• POST merges the body over the saved task input. GET uses the saved input only.
• outputRecordKey selects a different key-value store record (default OUTPUT).
• Query parameters: build (owner only, see above), memory, timeout, maxItems, forcePermissionLevel, and webhooks (base64 only; a body webhooks key is not read here). maxTotalChargeUsd and restartOnError come from the task's options.
• timeout sets the run's timeout. The request waits for timeout seconds or 45 seconds, whichever is shorter. Without timeout, the run keeps the task's timeout and may continue after the request gives up.

These status codes differ from the Actor endpoints, which return 200, {} for a missing record, and 408 run-timeout-exceeded.

On a 408, wait for the run with GET /v2/actor-runs/{runId}?waitForFinish=60 instead of calling run-sync again, which starts another run.

curl -X POST https://api.scrape.ly/v2/actor-tasks/tAsKiDeXaMpLe123/run-sync \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Get dataset items synchronously

Same wait rules as run-sync. On success, returns the run's dataset items with status 201. It accepts every Get dataset items parameter (format, fields, offset, limit, desc, and so on) and sends the X-Apify-Pagination-* headers.

Last task run

The most recent run of the task. Optional status and waitForFinish (up to 60; the wait stops at 45 seconds). If there's no matching run, returns 404 run-not-found.

Last-run storage shortcuts

Every shortcut accepts status and waitForFinish.

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  "https://api.scrape.ly/v2/actor-tasks/tAsKiDeXaMpLe123/runs/last/key-value-store/records/OUTPUT?status=SUCCEEDED"

Run objects, abort, resurrect, and logs for a known runId are documented under Actor runs.

Publish a task

Publishing turns a task into a public example for its Actor. The example gets its own page in the Store, under the Actor's Examples tab, showing the task's input. Values of input fields the Actor's schema marks as secret are masked on that page.

You can publish a task when:

• you own both the task and the Actor,
• the Actor is public, not deprecated, and has a successful build,
• the task input is a non-empty object, and
• the User Build has a valid input schema (the default build when none is set).

The Actor can have up to 50 published tasks.

Optional publish body fields:

Both endpoints return the task under data. Unpublishing keeps the SEO fields, so you can publish again later. If you change the slug, the old slug redirects to the new one.

Duplicate a task

Copies a task into your account, with its input and options. You can duplicate your own tasks and other users' published examples. When you copy someone else's example, secret input fields are left out of the copy. The new task gets a free name based on the original.

Returns 201 with the new task and a Location header. If you are at your task limit, returns 403 limit-reached.

Task webhooks

Lists your webhooks whose condition names this task. See List webhooks of a task. To find the automations that use a saved input, call GET /v2/automations?savedInputId={taskId} (see Automations API).

Public example tasks

Read the published examples of a public Actor. No authentication. {actorId} must be the Actor ID here, not username~name.

• The list returns { "data": { "total", "count", "items": [...] } }, newest first. Each item has id, name, title, publicSlug, seoTitle, seoDescription, useCase, publishedAt, actId, actName, actUsername, and actTitle.
• A single example returns the same fields plus the masked input and duplicateUrl, the duplicate endpoint for that task.
• The .md variant returns the example as Markdown, which is handy for AI agents.