List Runs
Retrieve a paginated list of all runs for a specific squid
https://api.lobstr.io/v1/runsThis endpoint retrieves a paginated list of all runs for a specific squid. Use this to view run history and track past executions.
Headers
AuthorizationstringheaderrequiredYour API authentication token. Value: Token YOUR_API_KEY
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| squid | string | Yes | The squid hash ID to list runs for |
| page | integer | No | Page number for pagination. Default: 1 |
| limit | integer | No | Results per page. Default: 50, Max: 100 |
Response Field Explanations
total_resultsintegerTotal number of runs. Example: 4
limitintegerMaximum results per page. Example: 50
pageintegerCurrent page number. Example: 1
total_pagesintegerTotal number of pages. Example: 1
dataarrayArray of run objects. Example: [...]
data[].idstringUnique run identifier. Example: "381cfbb47e474782857ddc035298b6f3"
data[].statusstringCurrent run status. Example: "done"
data[].is_donebooleanWhether the run has completed. Example: true
data[].total_resultsintegerNumber of results collected. Example: 156
data[].durationfloatRun duration in seconds. Example: 3.1849
data[].credit_usedfloatCredits consumed. Example: 3.1849
data[].expires_atstring | nullWhen 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"
data[].done_reasonstring | nullReason for completion. Example: "tasks_done"
nextstring | nullURL for next page (null if last page). Example: null
previousstring | nullURL for previous page (null if first page). Example: null
Use this endpoint to monitor all past and current runs for a squid.
Runs are returned in reverse chronological order (newest first).
Check is_done to quickly filter completed vs. active runs.
Code Examples
curl -X GET "https://api.lobstr.io/v1/runs?squid=b6c56d18cb0046949461ba9ca278e8ad&page=1&limit=50" \ -H "Authorization: Token YOUR_API_KEY"
Response
{ "total_results": 4, "limit": 50, "page": 1, "total_pages": 1, "result_from": 1, "result_to": 4, "data": [ { "id": "381cfbb47e474782857ddc035298b6f3", "object": "run", "squid": "b6c56d18cb0046949461ba9ca278e8ad", "is_done": true, "started_at": "2025-02-04T10:25:13Z", "total_results": 156, "total_unique_results": 156, "next_launch_at": null, "ended_at": "2025-02-04T10:25:21Z", "duration": 8.0415, "credit_used": 8.0415, "origin": "user", "force_launch": false, "status": "done", "export_done": true, "export_count": 1, "export_time": "2025-02-04T10:25:25Z", "expires_at": "2025-03-22T00:00:00Z", "email_done": null, "email_time": null, "created_at": "2025-02-04T10:25:13Z", "done_reason": "tasks_done", "done_reason_desc": null }, { "id": "3aa75b3f05c144f6a87f8397e229024e", "object": "run", "squid": "b6c56d18cb0046949461ba9ca278e8ad", "is_done": true, "started_at": "2025-01-29T09:53:27Z", "total_results": 0, "total_unique_results": 0, "next_launch_at": null, "ended_at": "2025-01-29T09:53:33Z", "duration": 0.0466, "credit_used": 0.0466, "origin": "user", "force_launch": false, "status": "done", "export_done": true, "export_count": 1, "export_time": "2025-01-29T09:53:37Z", "expires_at": null, "email_done": null, "email_time": null, "created_at": "2025-01-29T09:53:27Z", "done_reason": "tasks_done", "done_reason_desc": null } ], "next": null, "previous": null }