# Get Run

Retrieve detailed information about a specific run

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

<ParamField header="Authorization" type="string" required>
  Your API authentication token. Value: `Token YOUR_API_KEY`
</ParamField>

## Path Parameters

<ParamField path="run_hash" type="string" required>
  The unique identifier (hash) of the run. Example: `0393be3ea6f74986906153df1c3f9894`
</ParamField>

## Response Field Explanations

<ResponseField name="id" type="string">
  Unique identifier of the squid run. Example: `"0393be3ea6f74986906153df1c3f9894"`
</ResponseField>

<ResponseField name="object" type="string">
  Type of returned object (always "run"). Example: `"run"`
</ResponseField>

<ResponseField name="created_at" type="string">
  Date and time when the run was initially created (ISO 8601). Example: `"2025-02-04T10:26:50.847633"`
</ResponseField>

<ResponseField name="started_at" type="string">
  Date and time when the scraping run started executing. Example: `"2025-02-04T10:25:41.623683"`
</ResponseField>

<ResponseField name="ended_at" type="string | null">
  Date and time when the scraping run completed or stopped. Example: `"2025-02-04T10:26:52.222239"`
</ResponseField>

<ResponseField name="duration" type="float">
  Duration of the scraping run in seconds. Example: `50.1833`
</ResponseField>

<ResponseField name="credit_used" type="float">
  Total credits consumed during the run. Example: `50.1833`
</ResponseField>

<ResponseField name="origin" type="string">
  Origin of the run initiation (e.g., "user", "schedule"). Example: `"user"`
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the squid run (see statuses table). Example: `"done"`
</ResponseField>

<ResponseField name="total_results" type="integer">
  Total number of results collected. Example: `40`
</ResponseField>

<ResponseField name="total_unique_results" type="integer">
  Number of unique results collected. Example: `40`
</ResponseField>

<ResponseField name="export_done" type="boolean">
  Indicates if the export was successfully generated. Example: `true`
</ResponseField>

<ResponseField name="export_time" type="string | null">
  Date and time when export was generated. Example: `"2025-02-04T10:26:53.780636"`
</ResponseField>

<ResponseField name="expires_at" type="string | 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](https://staging.docs.lobstr.io/docs/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"`
</ResponseField>

<ResponseField name="done_reason" type="string | null">
  Reason indicating why the run finished (see done reasons table). Example: `"tasks_done"`
</ResponseField>

<ResponseField name="done_reason_desc" type="string | null">
  Additional description providing context for done_reason. Example: `null`
</ResponseField>

<ResponseField name="squid" type="string">
  Identifier of the squid this run belongs to. Example: `"e445405ef4ab41208ef7d29b92a1a9dd"`
</ResponseField>

<ResponseField name="next_launch_at" type="string | null">
  Scheduled date/time for the next execution (if recurring). Example: `null`
</ResponseField>

<ResponseField name="force_launch" type="boolean">
  Whether this run was force-launched. Example: `false`
</ResponseField>

<ResponseField name="export_count" type="integer">
  Number of times results have been exported. Example: `1`
</ResponseField>

<ResponseField name="mail_done" type="boolean">
  Whether the email delivery was completed. Example: `false`. Note: this specific endpoint names the field `mail_done`/`mail_time` — [List Runs](https://staging.docs.lobstr.io/docs/list-runs) and [Start Run](https://staging.docs.lobstr.io/docs/start-run) return the same data as `email_done`/`email_time` instead.
</ResponseField>

<ResponseField name="mail_time" type="string | null">
  Timestamp when email delivery completed. Example: `null`
</ResponseField>

<ResponseField name="email_verification" type="string | null">
  Email verification status for delivery. Example: `null`
</ResponseField>

<Note>
  This endpoint does not return an `is_done` field. Use [Get Run Stats](https://staging.docs.lobstr.io/docs/get-run-stats) if you need a live `is_done` flag while a run is in progress.
</Note>

## 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 |

<Tip>
  Use the status field to track run progress. Poll this endpoint periodically for long-running scrapes.
</Tip>

<Note>
  The done_reason field provides insight into why a run ended - useful for debugging failed runs.
</Note>

<Warning>
  Runs with status 'error' or unexpected done_reasons may indicate account issues that need attention.
</Warning>

## Code Examples

<CodeGroup>
```bash cURL
curl -X GET "https://api.lobstr.io/v1/runs/0393be3ea6f74986906153df1c3f9894" \
  -H "Authorization: Token YOUR_API_KEY"
```

```python Python
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']}")
```
</CodeGroup>

## Response

```json 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
}
```

```json 404
{
  "error": {
    "message": "Run not found",
    "type": "not_found_error",
    "param": "run_hash"
  }
}
```
