Scrape.ly - Use Actors

Use Actors

Start here: find, run, and automate ready-made Actors, and what runs cost.

An Actor is a ready-made cloud program: a scraper, a crawler, an automation, or an AI tool. You give it input, it runs in its own container on Scrape.ly, and it leaves results you can view, export, or send to other tools. You don't write or host any code.

.bash

curl -X POST "https://api.scrape.ly/v2/actors/<username>~<actor-name>/run-sync-get-dataset-items?format=json" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls": [{"url": "https://example.com"}]}'

That one call runs an Actor, waits for it, and returns its results. The rest of this page explains the pieces.

What an Actor is, from the user's side

You work with	What it is
Input	The run's settings, such as start URLs, search terms, or limits. Always a JSON object; the dashboard shows it as a form.
Runs	Each start creates a run with its own ID, status, log, and cost. Runs are billed to you, not to the Actor's author.
Results	Each run gets a default dataset (result items, exportable as JSON, CSV, Excel, and more) and a default key-value store (files and records such as `OUTPUT` or screenshots).

Authors publish Actors in the Store. You can also run Actors you built yourself; see Build Actors.

The path

Find an Actor in the Store and check its pricing, reviews, and README. Store
Run it. Fill in the form or paste JSON, optionally set memory, timeout, and a maximum cost, then click Start. Or describe what you need to the AI chat, which finds an Actor, runs it, and summarizes the results. Run Actors
Get the results. Watch the log, open the dataset, and export it. Results & exports
Automate. Save the input, then let an automation run it on a schedule or after another run, keep only what matters, add an AI summary, and send the results by email, Slack, or webhook. Automations
Call it from code or AI agents with the JavaScript client, the Python client, the REST API, or the MCP server.
Watch spend and limits under Billing. Account

End-to-end example

In the dashboard

Open the dashboard, click Store, and open an Actor.
On the Input tab, fill in the form (or switch to JSON) and click Start. Start runs exactly what the form shows; the Input dropdown above the form loads your saved inputs and the Actor's examples.
Follow the Log tab until the status is Succeeded.
Open Storage → Dataset and click Export.

With the API

Get a token under Settings → API & Integrations. The body is the Actor's input; the Input tab's JSON view shows the field names.

Synchronous endpoints like the one at the top of this page wait at most 45 seconds, then return 408 while the run keeps going. For longer jobs, start the run, then fetch the items when it's done:

.bash

# Start the run. The response has data.id and data.defaultDatasetId.
curl -X POST "https://api.scrape.ly/v2/actors/<username>~<actor-name>/runs" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls": [{"url": "https://example.com"}]}'

# Once the run's status is SUCCEEDED
curl "https://api.scrape.ly/v2/datasets/<defaultDatasetId>/items?format=csv" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN"

All run endpoints and options: Run Actors.

What a run costs

Runs are charged to the account that starts them. A run's cost is platform usage plus the Actor's fee.

Platform usage applies to every run, free Actors included:

Item	Billed by
Compute units (CU)	1 CU = 1 GB of memory for one hour. A 2 GB run that takes 30 minutes uses 1 CU.
Storage	Dataset, key-value store, and request queue reads and writes, plus storage held over time
Data transfer	For example, downloading results through the API
Proxy traffic	Per GB of datacenter or residential proxy traffic, if the Actor uses Scrape.ly proxies
Browser credits	Only if the Actor uses the Scrape.ly browser: its session time and the browser's proxy traffic
AI model tokens	Only if the Actor calls the LLM gateway: the model provider's cost per request plus a markup

Prices for your plan are under Billing → Pricing.

The Actor's fee depends on the author's pricing model:

Model	Shown as	You pay
Free	Free	Platform usage only
Pay per event	`$x/<event>`, `$x/result`, or "From $x"	A price per event the Actor charges, for example per page, per result item or per Actor start

You never pay an Actor fee on your own Actor.

Reservation. Before a run starts, Scrape.ly reserves timeout (hours) × memory (GB) × CU price, plus one of each priced event. If your balance can't cover it, the run is rejected with 402 Payment Required. A lower timeout or memory lowers the reservation. After the run you pay actual usage and the rest is released.

The run page shows the final cost; click it for a breakdown by item. Account-wide spend is under Billing → Current period and Historical usage.