Skip to content
Run

List Runs

Retrieve a paginated list of all runs for a specific squid

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

This endpoint retrieves a paginated list of all runs for a specific squid. Use this to view run history and track past executions.

Headers

Authorizationstringheaderrequired

Your 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_resultsinteger

Total number of runs. Example: 4

limitinteger

Maximum results per page. Example: 50

pageinteger

Current page number. Example: 1

total_pagesinteger

Total number of pages. Example: 1

dataarray

Array of run objects. Example: [...]

data[].idstring

Unique run identifier. Example: "381cfbb47e474782857ddc035298b6f3"

data[].statusstring

Current run status. Example: "done"

data[].is_doneboolean

Whether the run has completed. Example: true

data[].total_resultsinteger

Number of results collected. Example: 156

data[].durationfloat

Run duration in seconds. Example: 3.1849

data[].credit_usedfloat

Credits consumed. Example: 3.1849

data[].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"

data[].done_reasonstring | null

Reason for completion. Example: "tasks_done"

nextstring | null

URL for next page (null if last page). Example: null

previousstring | null

URL 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

200
{
  "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
}