---
title: "Use Actors · Scrape.ly Docs"
description: "Start here: find, run, and automate ready-made Actors, and what runs cost."
url: https://scrape.ly/docs/use-actors
markdown: https://scrape.ly/docs/use-actors.md
---

# 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](https://scrape.ly/docs/store.md). You can also run Actors you built yourself; see [Build Actors](https://scrape.ly/docs/quickstart.md).

## The path

1. **Find an Actor** in the Store and check its pricing, reviews, and README. [Store](https://scrape.ly/docs/store.md)
2. **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](https://scrape.ly/docs/ai-chat.md), which finds an Actor, runs it, and summarizes the results. [Run Actors](https://scrape.ly/docs/run-actors.md)
3. **Get the results.** Watch the log, open the dataset, and export it. [Results & exports](https://scrape.ly/docs/results.md)
4. **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](https://scrape.ly/docs/automations.md)
5. **Call it from code or AI agents** with the [JavaScript client](https://scrape.ly/docs/client-js.md), the [Python client](https://scrape.ly/docs/client-python.md), the [REST API](https://scrape.ly/docs/api.md), or the [MCP server](https://scrape.ly/docs/mcp.md).
6. **Watch spend and limits** under **Billing**. [Account](https://scrape.ly/docs/account.md)

## End-to-end example

### In the dashboard

1. Open the [dashboard](https://my.scrape.ly), click **Store**, and open an Actor.
2. 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.
3. Follow the **Log** tab until the status is **Succeeded**.
4. 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](https://scrape.ly/docs/run-actors.md#run-from-the-api).

## 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](https://scrape.ly/docs/browser.md): its session time and the browser's proxy traffic |
| AI model tokens | Only if the Actor calls the [LLM gateway](https://scrape.ly/docs/llm-gateway.md): 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.

> [!TIP]
> Cap spending with **Maximum cost per run** in the dashboard or `maxTotalChargeUsd` in the API. The cap covers everything above, including browser credits, AI model tokens, and the Actor fee. When it's reached, the run stops. See [Run options](https://scrape.ly/docs/run-actors.md#run-options).

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**.

> [!NOTE]
> Concurrency, memory, and other account limits are under **Billing** → **Limits** and in `GET /v2/users/me/limits`. See [Limits and errors](https://scrape.ly/docs/run-actors.md#limits-and-errors).

## What's next

- [Find Actors in the Store](https://scrape.ly/docs/store.md)
- [Run Actors](https://scrape.ly/docs/run-actors.md)
- [AI chat](https://scrape.ly/docs/ai-chat.md)
- [Results & exports](https://scrape.ly/docs/results.md)
- [Automations](https://scrape.ly/docs/automations.md)
- [Integrations](https://scrape.ly/docs/integrations.md)

---

- Next: [Find Actors in the Store](https://scrape.ly/docs/store.md)
- All docs: [Docs index](https://scrape.ly/docs.md), [llms.txt](https://scrape.ly/llms.txt)