Skip to content
Squid

List Squids

Retrieve a paginated list of all your squids with filtering and search capabilities

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/squids

This endpoint returns a paginated list of all squids belonging to the authenticated user. You can search by name and control pagination with query parameters.

Headers

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Query Parameters

namestringquery

Filter squids by name (case-insensitive partial match). Example: Google

limitintegerquery

Number of results per page. Example: 10

pageintegerquery

Page number for pagination. Example: 2

sortstringquery

Order of the list, applied before pagination. Omit it for the default order, newest squid first. activity lists squids with a run in progress first, then by their latest run, then newest first: the order the dashboard uses. Example: activity

Response Structure

total_resultsinteger

Total number of squids matching the query. Example: 15

limitinteger

Number of results per page. Example: 50

pageinteger

Current page number. Example: 1

total_pagesinteger

Total number of pages available. Example: 1

result_frominteger

Starting index of results in current page. Example: 1

result_tointeger

Ending index of results in current page. Example: 15

dataarray

Array of squid objects with comprehensive details

nextstring | null

Full URL to the next page (null if on last page). Example: null

previousstring | null

Full URL to the previous page (null if on first page). Example: null

Squid Object Fields

data[].idstring

Unique squid identifier. Example: "c106a44a98044ef18acc59986ae10967"

data[].namestring

Display name of the squid. Example: "Google Maps (1)"

data[].created_atstring

Timestamp when the squid was created. Example: "2024-01-15T10:30:00Z"

data[].created_viastring | null

Which surface created this squid — "api", "sdk", "cli", or "mcp". null for squids created in the dashboard. Example: "cli"

data[].is_activeboolean

Whether the squid is active and can run. Example: true

data[].deactivation_reasonstring | null

Why the squid was deactivated, or null while it is active. Example: null

data[].is_readyboolean

Whether the squid has tasks and is ready to run. Example: true

data[].crawlerstring

Unique identifier of the associated crawler. Example: "4734d096159ef05210e0e1677e8be823"

data[].crawler_namestring

Display name of the crawler. Example: "Google Maps Search Export"

data[].iconstring

URL to the crawler's icon image. Example: "https://cdn.lobstr.io/icons/google-maps.png"

data[].is_publicboolean

Whether the crawler is publicly available. Example: true

data[].concurrencyinteger

Number of concurrent tasks the squid runs. Example: 2

data[].paramsobject

Crawler-specific parameter configuration object. Example: {"language": "en"}

data[].to_completeboolean

Whether to stop after completing all tasks. Example: false

data[].export_unique_resultsboolean

Whether to export only unique results. Example: true

data[].no_line_breaksboolean

Whether to remove line breaks from exported data. Example: false

data[].last_run_statusstring

Status of the most recent run (completed, running, error, etc.). Example: "DONE"

data[].last_run_atstring

Timestamp of the most recent run. Example: "2024-01-20T15:45:00Z"

data[].total_runsinteger

Total number of times the squid has been executed. Example: 5

data[].next_launch_atstring | null

Scheduled time for the next automated run (null if not scheduled). Example: "2024-01-21T10:00:00Z"

data[].google_sheet_fieldsobject | null

Google Sheets integration configuration (null if not configured). Example: null

data[].ftp_fieldsobject | null

FTP integration configuration (null if not configured). Example: null

data[].s3_fieldsobject | null

AWS S3 integration configuration (null if not configured). Example: null

data[].webhook_fieldsobject | null

Webhook integration configuration (null if not configured). Example: null

data[].schedulestring | null

Cron expression for scheduled runs (null if not scheduled). Example: "0 10 * * *"

data[].schedule_timestring

Human-readable schedule description. Example: "Daily at 10:00 AM"

data[].download_urlstring | null

Temporary signed URL to download results (null if no results available). Example: "https://storage.lobstr.io/downloads/xyz123..."

Use the 'name' query parameter to quickly find squids. It performs a case-insensitive partial match on squid names.

The 'next' and 'previous' fields contain full URLs for easy pagination. Use them directly to navigate through pages.

Check 'last_run_status' to see if a squid has completed, is running, or encountered errors. Useful for monitoring multiple squids.

Squids with 'is_ready: false' haven't been configured with tasks yet. Add tasks before starting a run.

The 'download_url' field provides a temporary signed URL to download results. URLs expire after a certain time period.

Code Examples

curl -X GET "https://api.lobstr.io/v1/squids?name=Google&limit=10&page=1" \
  -H "Authorization: Token YOUR_API_KEY"

Response

200
{
  "total_results": 34,
  "limit": 10,
  "page": 1,
  "total_pages": 4,
  "result_from": 1,
  "result_to": 10,
  "data": [
    {
      "id": "e86b29c032024b66aff529e1d43c2bd7",
      "created_at": "2025-02-03T14:24:23Z",
      "created_via": "api",
      "name": "My Google Maps Scraper",
      "is_ready": true,
      "is_active": true,
      "deactivation_reason": null,
      "concurrency": 2,
      "params": {
        "country": "United States",
        "ratings": "4.0+",
        "language": "English (United States)",
        "max_results": 150
      },
      "crawler": "4734d096159ef05210e0e1677e8be823",
      "crawler_name": "Google Maps Search Export",
      "last_run_status": "DONE",
      "total_runs": 5,
      "last_run_at": "2025-03-05T09:27:17.012423",
      "next_launch_at": null,
      "is_public": true
    }
  ],
  "next": "https://api.lobstr.io/v1/squids?limit=10&page=2",
  "previous": null
}