Skip to main content
POST
/
v1
/
runs
Start Run
curl --request POST \
  --url https://api.lobstr.io/v1/runs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "squid": "<string>"
}
'
{
  "id": "<string>",
  "object": "<string>",
  "squid": "<string>",
  "status": "<string>",
  "is_done": true,
  "started_at": "<string>",
  "origin": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.lobstr.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Headers

​
Authorization
string
required
Your API authentication token. Value: Token YOUR_API_KEY
​
Content-Type
string
required
Must be application/json. Value: application/json

​
Request Body

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

​
Response Field Explanations

​
id
string
Unique identifier of the new run. Example: "dd3473abe4cb41b683551e851edded94"
​
object
string
Always “run”. Example: "run"
​
squid
string
The squid being executed. Example: "b6c56d18cb0046949461ba9ca278e8ad"
​
status
string
Initial run status (typically “pending”). Example: "pending"
​
is_done
boolean
Whether the run has completed (false for new runs). Example: false
​
started_at
string
Run start timestamp. Example: "2025-02-10T14:27:45Z"
​
origin
string
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,
  "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"
  }
}