Get Run
curl --request GET \
--url https://api.lobstr.io/v1/runs/{run_hash} \
--header 'Authorization: <authorization>'import requests
url = "https://api.lobstr.io/v1/runs/{run_hash}"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.lobstr.io/v1/runs/{run_hash}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lobstr.io/v1/runs/{run_hash}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.lobstr.io/v1/runs/{run_hash}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.lobstr.io/v1/runs/{run_hash}")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.lobstr.io/v1/runs/{run_hash}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"created_at": "<string>",
"started_at": "<string>",
"ended_at": {},
"duration": 123,
"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,
"mail_done": true,
"mail_time": {},
"email_verification": {}
}Run
Get Run
Retrieve detailed information about a specific run
GET
/
v1
/
runs
/
{run_hash}
Get Run
curl --request GET \
--url https://api.lobstr.io/v1/runs/{run_hash} \
--header 'Authorization: <authorization>'import requests
url = "https://api.lobstr.io/v1/runs/{run_hash}"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.lobstr.io/v1/runs/{run_hash}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lobstr.io/v1/runs/{run_hash}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.lobstr.io/v1/runs/{run_hash}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.lobstr.io/v1/runs/{run_hash}")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.lobstr.io/v1/runs/{run_hash}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"created_at": "<string>",
"started_at": "<string>",
"ended_at": {},
"duration": 123,
"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,
"mail_done": true,
"mail_time": {},
"email_verification": {}
}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
string
required
Your API authentication token. Value:
Token YOUR_API_KEYPath Parameters
string
required
The unique identifier (hash) of the run. Example:
0393be3ea6f74986906153df1c3f9894Response Field Explanations
string
Unique identifier of the squid run. Example:
"0393be3ea6f74986906153df1c3f9894"string
Type of returned object (always “run”). Example:
"run"string
Date and time when the run was initially created (ISO 8601). Example:
"2025-02-04T10:26:50.847633"string
Date and time when the scraping run started executing. Example:
"2025-02-04T10:25:41.623683"string | null
Date and time when the scraping run completed or stopped. Example:
"2025-02-04T10:26:52.222239"float
Duration of the scraping run in seconds. Example:
50.1833float
Total credits consumed during the run. Example:
50.1833string
Origin of the run initiation (e.g., “user”, “schedule”). Example:
"user"string
Current status of the squid run (see statuses table). Example:
"done"integer
Total number of results collected. Example:
40integer
Number of unique results collected. Example:
40boolean
Indicates if the export was successfully generated. Example:
truestring | null
Date and time when export was generated. Example:
"2025-02-04T10:26:53.780636"string | null
Reason indicating why the run finished (see done reasons table). Example:
"tasks_done"string | null
Additional description providing context for done_reason. Example:
nullstring
Identifier of the squid this run belongs to. Example:
"e445405ef4ab41208ef7d29b92a1a9dd"string | null
Scheduled date/time for the next execution (if recurring). Example:
nullboolean
Whether this run was force-launched. Example:
falseinteger
Number of times results have been exported. Example:
1boolean
string | null
Timestamp when email delivery completed. Example:
nullstring | null
Email verification status for delivery. Example:
nullThis endpoint does not return an
is_done field. Use Get Run Stats if you need a live is_done flag while a run is in progress.Run Statuses
| Status | Phase | Description |
|---|---|---|
| PENDING | Waiting | Run is created and waiting to start execution |
| RUNNING | In Progress | Run is currently collecting data |
| UPLOADING | In Progress | Data collection is complete, now uploading/exporting results |
| PAUSED | In Progress | Run has been temporarily paused; it can resume or be aborted |
| ABORTED | Completed | Run was manually stopped before completion |
| DONE | Completed | Run finished all tasks and exported the results successfully |
| ERROR | Completed | Run failed due to an error |
Done Reasons
| Reason | Description |
|---|---|
| tasks_done | All assigned tasks completed successfully |
| aborted | Scraping run manually aborted by user |
| no_credits_left | No credits remaining |
| no_account_available | No available accounts; refresh required |
| no_accounts | No scraper-linked accounts available to initiate run |
| cookies_expired | Scraper-linked account cookies expired; renewal required |
| wrong_credentials | Account credentials invalid |
| checkpoint_reached | Account is blocked at a checkpoint (manual verification required) |
| otp_needed | OTP verification required; please re-sync accounts |
| limit_exceeded | Scraper-linked account limit exceeded |
| slots_limit_exceeded | Scraping slots limit exceeded |
| too_many_requests | Run stopped due to excessive requests |
| batch_wait | Current batch completed; awaiting timeout |
| deactivated | Run has been deactivated |
| maintenance_fees_not_paid | Maintenance fees for this custom module have not been paid |
| last_invoice_not_paid | Previous invoice payment pending |
| export_fix | Export 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"
import requests
url = "https://api.lobstr.io/v1/runs/0393be3ea6f74986906153df1c3f9894"
headers = {
"Authorization": "Token YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
run = response.json()
print(f"Run ID: {run['id']}")
print(f"Status: {run['status']}")
print(f"Started: {run['started_at']}")
print(f"Duration: {run['duration']}")
print(f"Credits Used: {run['credit_used']}")
print(f"Total Results: {run['total_results']}")
if run['status'] in ['done', 'aborted', 'error']:
print(f"Done Reason: {run['done_reason']}")
print(f"Export Ready: {run['export_done']}")
Response
200
{
"id": "0393be3ea6f74986906153df1c3f9894",
"object": "run",
"squid": "e445405ef4ab41208ef7d29b92a1a9dd",
"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": 50.1833,
"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",
"mail_done": false,
"mail_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"
}
}