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

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

## Query Parameters

<ParamField query="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="string">
  Duration of the scraping run as a formatted timedelta string. Example: `"0:00:50.183300"`
</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="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="email_done" type="boolean">
  Whether the email delivery was completed. Example: `false`
</ResponseField>

<ResponseField name="email_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>

<ResponseField name="is_done" type="boolean">
  Shorthand flag indicating whether the run has completed (any terminal status). Example: `true`
</ResponseField>

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

<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 theme={null}
  curl -X GET "https://api.lobstr.io/v1/runs/0393be3ea6f74986906153df1c3f9894" \
    -H "Authorization: Token YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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 theme={null}
{
  "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
}
```

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