Skip to content
Run

Get Run

Retrieve detailed information about a specific run

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.
GEThttps://api.lobstr.io/v1/runs/{run_hash}

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

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Path Parameters

run_hashstringpathrequired

The unique identifier (hash) of the run. Example: 0393be3ea6f74986906153df1c3f9894

Response Field Explanations

idstring

Unique identifier of the squid run. Example: "0393be3ea6f74986906153df1c3f9894"

objectstring

Type of returned object (always "run"). Example: "run"

created_atstring

Date and time when the run was initially created (ISO 8601). Example: "2025-02-04T10:26:50.847633"

started_atstring

Date and time when the scraping run started executing. Example: "2025-02-04T10:25:41.623683"

ended_atstring | null

Date and time when the scraping run completed or stopped. Example: "2025-02-04T10:26:52.222239"

durationfloat

Duration of the scraping run in seconds. Example: 50.1833

credit_usedfloat

Total credits consumed during the run. Example: 50.1833

originstring

Origin of the run initiation (e.g., "user", "schedule"). Example: "user"

statusstring

Current status of the squid run (see statuses table). Example: "done"

total_resultsinteger

Total number of results collected. Example: 40

total_unique_resultsinteger

Number of unique results collected. Example: 40

export_doneboolean

Indicates if the export was successfully generated. Example: true

export_timestring | null

Date and time when export was generated. Example: "2025-02-04T10:26:53.780636"

expires_atstring | null

When this run's results stop being downloadable (UTC): the first midnight UTC after export_time plus the days your plan keeps results (Free 7, paid plans 45, plans of 1,000,000 credits a month or more 90). From then on Download Run answers DataRetentionPeriodExceeded. Your current plan counts: upgrading opens older runs again, within 90 days of their export. null when the run has no results or is not exported yet. Example: "2025-03-22T00:00:00Z"

done_reasonstring | null

Reason indicating why the run finished (see done reasons table). Example: "tasks_done"

done_reason_descstring | null

Additional description providing context for done_reason. Example: null

squidstring

Identifier of the squid this run belongs to. Example: "e445405ef4ab41208ef7d29b92a1a9dd"

next_launch_atstring | null

Scheduled date/time for the next execution (if recurring). Example: null

force_launchboolean

Whether this run was force-launched. Example: false

export_countinteger

Number of times results have been exported. Example: 1

mail_doneboolean

Whether the email delivery was completed. Example: false. Note: this specific endpoint names the field mail_done/mail_time — List Runs and Start Run return the same data as email_done/email_time instead.

mail_timestring | null

Timestamp when email delivery completed. Example: null

email_verificationstring | null

Email verification status for delivery. Example: null

This 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 Your other runs in progress used all your plan's slots when this run was due to start
too_many_requests Run stopped due to excessive requests
batch_wait Current batch completed; awaiting timeout
waiting_sending_slot Leboncoin Auto Message Sender: waiting for a free sending slot; the run resumes in about 10 minutes
message_preparation_stopped Leboncoin Auto Message Sender: the message could not be prepared; the run log gives the exact reason
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"

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",
  "expires_at": "2025-03-22T00:00:00Z",
  "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"
  }
}