Skip to content
Run

Start Run

Initiate a new run for a specified squid

The v1 API, for batchesSquids, tasks and runs: many calls on a schedule, delivered where you work. For one call that answers in seconds, use the API v2.
POSThttps://api.lobstr.io/v1/runs

This endpoint initiates a new run for a specified squid, starting the scraping process for all active tasks within that squid.

Headers

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Content-Typestringheaderrequired

Must be application/json. Value: application/json

Request Body

squidstringrequired

The hash ID of the squid to run. Example: "b6c56d18cb0046949461ba9ca278e8ad"

Response Field Explanations

idstring

Unique identifier of the new run. Example: "dd3473abe4cb41b683551e851edded94"

objectstring

Always "run". Example: "run"

squidstring

The squid being executed. Example: "b6c56d18cb0046949461ba9ca278e8ad"

statusstring

Initial run status (typically "pending"). Example: "pending"

is_doneboolean

Whether the run has completed (false for new runs). Example: false

started_atstring

Run start timestamp. Example: "2025-02-10T14:27:45Z"

originstring

Origin of the run ("user" for API-initiated runs). Example: "user"

Save the returned run ID to track progress using Get Run or Get Run Stats endpoints.

Ensure your squid has active tasks before starting a run, or the run will complete immediately with no results.

Only one run can be active per squid at a time. Starting a new run while one is active will return an error.

For crawlers requiring accounts (e.g., LinkedIn, Facebook), ensure you have synced accounts before starting a run.

Code Examples

curl -X POST "https://api.lobstr.io/v1/runs" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "squid": "b6c56d18cb0046949461ba9ca278e8ad"
  }'

Response

200
{
  "id": "dd3473abe4cb41b683551e851edded94",
  "object": "run",
  "squid": "b6c56d18cb0046949461ba9ca278e8ad",
  "is_done": false,
  "started_at": "2025-02-10T14:27:45Z",
  "total_results": 0,
  "total_unique_results": 0,
  "next_launch_at": null,
  "ended_at": null,
  "duration": 0,
  "credit_used": 0,
  "origin": "user",
  "force_launch": false,
  "status": "pending",
  "export_done": null,
  "export_count": 0,
  "export_time": null,
  "expires_at": null,
  "email_done": null,
  "email_time": null,
  "created_at": "2025-02-10T14:27:45Z",
  "done_reason": null,
  "done_reason_desc": null
}
400
{
  "error": {
    "message": "A run is already active for this squid",
    "type": "validation_error",
    "param": "squid"
  }
}