Skip to main content
GET
/
v1
/
runs
/
{run_hash}
Get Run
curl --request GET \
  --url https://api.lobstr.io/v1/runs/{run_hash} \
  --header 'Authorization: <authorization>'
{
  "id": "<string>",
  "object": "<string>",
  "created_at": "<string>",
  "started_at": "<string>",
  "ended_at": {},
  "duration": "<string>",
  "credit_used": 123,
  "origin": "<string>",
  "status": "<string>",
  "total_results": 123,
  "total_unique_results": 123,
  "export_done": true,
  "export_time": {},
  "done_reason": {},
  "done_reason_desc": {},
  "squid": "<string>",
  "next_launch_at": {},
  "force_launch": true,
  "export_count": 123,
  "email_done": true,
  "email_time": {},
  "email_verification": {},
  "is_done": true
}

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 retrieves detailed information about a specific run using its hash ID. A run represents an execution instance of a squid’s tasks, tracking progress, status, and results.

​
Headers

​
Authorization
string
required
Your API authentication token. Value: Token YOUR_API_KEY

​
Query Parameters

​
run_hash
string
required
The unique identifier (hash) of the run. Example: 0393be3ea6f74986906153df1c3f9894

​
Response Field Explanations

​
id
string
Unique identifier of the squid run. Example: "0393be3ea6f74986906153df1c3f9894"
​
object
string
Type of returned object (always “run”). Example: "run"
​
created_at
string
Date and time when the run was initially created (ISO 8601). Example: "2025-02-04T10:26:50.847633"
​
started_at
string
Date and time when the scraping run started executing. Example: "2025-02-04T10:25:41.623683"
​
ended_at
string | null
Date and time when the scraping run completed or stopped. Example: "2025-02-04T10:26:52.222239"
​
duration
string
Duration of the scraping run as a formatted timedelta string. Example: "0:00:50.183300"
​
credit_used
float
Total credits consumed during the run. Example: 50.1833
​
origin
string
Origin of the run initiation (e.g., “user”, “schedule”). Example: "user"
​
status
string
Current status of the squid run (see statuses table). Example: "done"
​
total_results
integer
Total number of results collected. Example: 40
​
total_unique_results
integer
Number of unique results collected. Example: 40
​
export_done
boolean
Indicates if the export was successfully generated. Example: true
​
export_time
string | null
Date and time when export was generated. Example: "2025-02-04T10:26:53.780636"
​
done_reason
string | null
Reason indicating why the run finished (see done reasons table). Example: "tasks_done"
​
done_reason_desc
string | null
Additional description providing context for done_reason. Example: null
​
squid
string
Identifier of the squid this run belongs to. Example: "e445405ef4ab41208ef7d29b92a1a9dd"
​
next_launch_at
string | null
Scheduled date/time for the next execution (if recurring). Example: null
​
force_launch
boolean
Whether this run was force-launched. Example: false
​
export_count
integer
Number of times results have been exported. Example: 1
​
email_done
boolean
Whether the email delivery was completed. Example: false
​
email_time
string | null
Timestamp when email delivery completed. Example: null
​
email_verification
string | null
Email verification status for delivery. Example: null
​
is_done
boolean
Shorthand flag indicating whether the run has completed (any terminal status). Example: true

​
Run Statuses

StatusPhaseDescription
PENDINGWaitingRun is created and waiting to start execution
RUNNINGIn ProgressRun is currently collecting data
UPLOADINGIn ProgressData collection is complete, now uploading/exporting results
PAUSEDIn ProgressRun has been temporarily paused; it can resume or be aborted
ABORTEDCompletedRun was manually stopped before completion
DONECompletedRun finished all tasks and exported the results successfully
ERRORCompletedRun failed due to an error

​
Done Reasons

ReasonDescription
tasks_doneAll assigned tasks completed successfully
abortedScraping run manually aborted by user
no_credits_leftNo credits remaining
no_account_availableNo available accounts; refresh required
no_accountsNo scraper-linked accounts available to initiate run
cookies_expiredScraper-linked account cookies expired; renewal required
wrong_credentialsAccount credentials invalid
checkpoint_reachedAccount is blocked at a checkpoint (manual verification required)
otp_neededOTP verification required; please re-sync accounts
limit_exceededScraper-linked account limit exceeded
slots_limit_exceededScraping slots limit exceeded
too_many_requestsRun stopped due to excessive requests
batch_waitCurrent batch completed; awaiting timeout
deactivatedRun has been deactivated
maintenance_fees_not_paidMaintenance fees for this custom module have not been paid
last_invoice_not_paidPrevious invoice payment pending
export_fixExport regenerated successfully after previous failure
Use the status field to track run progress. Poll this endpoint periodically for long-running scrapes.
The done_reason field provides insight into why a run ended - useful for debugging failed runs.
Runs with status ‘error’ or unexpected done_reasons may indicate account issues that need attention.

​
Code Examples

curl -X GET "https://api.lobstr.io/v1/runs/0393be3ea6f74986906153df1c3f9894" \
  -H "Authorization: Token YOUR_API_KEY"

​
Response

200
{
  "id": "0393be3ea6f74986906153df1c3f9894",
  "object": "run",
  "squid": "e445405ef4ab41208ef7d29b92a1a9dd",
  "is_done": true,
  "created_at": "2025-02-04T10:26:50.847633",
  "started_at": "2025-02-04T10:25:41.623683",
  "ended_at": "2025-02-04T10:26:52.222239",
  "next_launch_at": null,
  "duration": "0:00:50.183300",
  "credit_used": 50.1833,
  "origin": "user",
  "force_launch": false,
  "status": "done",
  "export_done": true,
  "export_count": 1,
  "export_time": "2025-02-04T10:26:53.780636",
  "email_done": false,
  "email_time": null,
  "email_verification": null,
  "total_results": 40,
  "total_unique_results": 40,
  "done_reason": "tasks_done",
  "done_reason_desc": null
}
404
{
  "error": {
    "message": "Run not found",
    "type": "not_found_error",
    "param": "run_hash"
  }
}