---
title: "API guide · Scrape.ly Docs"
description: "Authenticate, start a run, wait for it, and fetch the results with curl."
url: https://scrape.ly/docs/api
markdown: https://scrape.ly/docs/api.md
---

# API guide

> Authenticate, start a run, wait for it, and fetch the results with curl.

A short guide to authenticating, starting an Actor, waiting for it to finish, and reading the results. For request and response details, see the [API overview](https://scrape.ly/docs/api-overview.md) and the reference pages linked at the end. If you'd rather not write raw HTTP calls, use the [JavaScript client](https://scrape.ly/docs/client-js.md) or the [Python client](https://scrape.ly/docs/client-python.md).

**Base URL:** `https://api.scrape.ly`  
Public endpoints live under `/v2`.

## Authenticate

Create a token in the dashboard under **Settings → API & Integrations**. Send it as a Bearer token:

```bash
export SCRAPELY_TOKEN="scrapely_..."

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/users/me
```

```api-test
{ "method": "GET", "path": "/v2/users/me" }
```

The API only reads the token from the `Authorization` header. A `?token=` query parameter is ignored. Treat tokens like passwords.

## Start a run

`POST /v2/actors/{actorId}/runs` starts a run and returns right away. `{actorId}` is the Actor ID or the named ID `username~actor-name`.

The JSON body **is the Actor input object** at the top level. Do not wrap it in `{ "input": ... }` or `{ "runInput": ... }`.

```bash
curl -X POST https://api.scrape.ly/v2/actors/janedoe~my-actor/runs \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "maxResults": 50}'
```

Response (`201`, or `202` if the run is queued):

```json
{
  "data": {
    "id": "a7XyZ8kLmN2pQ4rSt",
    "actId": "eLN5rTB8sYTBWdfzx",
    "status": "READY",
    "defaultDatasetId": "dS9t8uVwXyZ12345",
    "defaultKeyValueStoreId": "kVxYzAbCdEf12345",
    "defaultRequestQueueId": "rQmNoPqRsT123456"
  }
}
```

Optional query parameters: `build`, `memory`, `timeout`, `maxItems`, `maxTotalChargeUsd`, `restartOnError`, `waitForFinish` (up to **60**; the wait stops at 45 seconds), `webhooks`, `forcePermissionLevel`. `build` is owner only: on someone else's Actor it's ignored and the run uses the [User Build](https://scrape.ly/docs/publishing.md#user-build). See [Start a run](https://scrape.ly/docs/api-actors.md#start-a-run).

## Poll until it finishes

For longer jobs, poll `GET /v2/actor-runs/{runId}` until `status` is terminal:

`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`.

```bash
RUN_ID=a7XyZ8kLmN2pQ4rSt

curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/actor-runs/$RUN_ID
```

```api-test
{ "method": "GET", "path": "/v2/actor-runs/{runId}" }
```

Prefer [webhooks](https://scrape.ly/docs/api-webhooks.md) over tight polling. `waitForFinish` on `POST .../runs` and on `GET /v2/actor-runs/{runId}` blocks for at most 45 seconds, so repeat the `GET` until `status` is terminal. For short jobs, `POST /v2/actors/{actorId}/run-sync` waits up to 45 seconds and returns the `OUTPUT` key-value record instead of the run object. See [Waiting for runs and builds](https://scrape.ly/docs/api-overview.md#waiting-for-runs-and-builds). See [Run Actor synchronously](https://scrape.ly/docs/api-actors.md#run-actor-synchronously).

## Fetch dataset items

Use `defaultDatasetId` from the run:

```bash
curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  "https://api.scrape.ly/v2/datasets/$DATASET_ID/items"
```

```api-test
{ "method": "GET", "path": "/v2/datasets/{datasetId}/items?limit=10" }
```

You can also skip the storage ID and read straight from the run: `GET /v2/actor-runs/{runId}/dataset/items` takes the same parameters. See [Run storages](https://scrape.ly/docs/api-runs.md#run-storages).

Named output (for example `OUTPUT`) is a record in the run's default key-value store:

```bash
curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/key-value-stores/$KVS_ID/records/OUTPUT
```

Logs are plain text:

```bash
curl -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  https://api.scrape.ly/v2/actor-runs/$RUN_ID/log
```

## Reference

- [API overview](https://scrape.ly/docs/api-overview.md): auth, pagination, errors, rate limits
- [Actors](https://scrape.ly/docs/api-actors.md): Actors, versions, builds, starting runs
- [Actor runs](https://scrape.ly/docs/api-runs.md): inspect, abort, resurrect, logs
- [Actor tasks](https://scrape.ly/docs/api-tasks.md): saved inputs and run configurations
- [Datasets](https://scrape.ly/docs/api-datasets.md) · [Key-value stores](https://scrape.ly/docs/api-key-value-stores.md) · [Request queues](https://scrape.ly/docs/api-request-queues.md)
- [Automations](https://scrape.ly/docs/api-automations.md) · [Webhooks](https://scrape.ly/docs/api-webhooks.md) · [Schedules](https://scrape.ly/docs/api-schedules.md)

---

- Previous: [API overview](https://scrape.ly/docs/api-overview.md)
- Next: [Actors](https://scrape.ly/docs/api-actors.md)
- All docs: [Docs index](https://scrape.ly/docs.md), [llms.txt](https://scrape.ly/llms.txt)