List Squids
Retrieve a paginated list of all your squids with filtering and search capabilities
https://api.lobstr.io/v1/squidsThis 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
AuthorizationstringheaderrequiredYour API authentication token. Value: Token YOUR_API_KEY
Query Parameters
namestringqueryFilter squids by name (case-insensitive partial match). Example: Google
limitintegerqueryNumber of results per page. Example: 10
pageintegerqueryPage number for pagination. Example: 2
sortstringqueryOrder 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_resultsintegerTotal number of squids matching the query. Example: 15
limitintegerNumber of results per page. Example: 50
pageintegerCurrent page number. Example: 1
total_pagesintegerTotal number of pages available. Example: 1
result_fromintegerStarting index of results in current page. Example: 1
result_tointegerEnding index of results in current page. Example: 15
dataarrayArray of squid objects with comprehensive details
nextstring | nullFull URL to the next page (null if on last page). Example: null
previousstring | nullFull URL to the previous page (null if on first page). Example: null
Squid Object Fields
data[].idstringUnique squid identifier. Example: "c106a44a98044ef18acc59986ae10967"
data[].namestringDisplay name of the squid. Example: "Google Maps (1)"
data[].created_atstringTimestamp when the squid was created. Example: "2024-01-15T10:30:00Z"
data[].created_viastring | nullWhich surface created this squid — "api", "sdk", "cli", or "mcp". null for squids created in the dashboard. Example: "cli"
data[].is_activebooleanWhether the squid is active and can run. Example: true
data[].deactivation_reasonstring | nullWhy the squid was deactivated, or null while it is active. Example: null
data[].is_readybooleanWhether the squid has tasks and is ready to run. Example: true
data[].crawlerstringUnique identifier of the associated crawler. Example: "4734d096159ef05210e0e1677e8be823"
data[].crawler_namestringDisplay name of the crawler. Example: "Google Maps Search Export"
data[].iconstringURL to the crawler's icon image. Example: "https://cdn.lobstr.io/icons/google-maps.png"
data[].is_publicbooleanWhether the crawler is publicly available. Example: true
data[].concurrencyintegerNumber of concurrent tasks the squid runs. Example: 2
data[].paramsobjectCrawler-specific parameter configuration object. Example: {"language": "en"}
data[].to_completebooleanWhether to stop after completing all tasks. Example: false
data[].export_unique_resultsbooleanWhether to export only unique results. Example: true
data[].no_line_breaksbooleanWhether to remove line breaks from exported data. Example: false
data[].last_run_statusstringStatus of the most recent run (completed, running, error, etc.). Example: "DONE"
data[].last_run_atstringTimestamp of the most recent run. Example: "2024-01-20T15:45:00Z"
data[].total_runsintegerTotal number of times the squid has been executed. Example: 5
data[].next_launch_atstring | nullScheduled time for the next automated run (null if not scheduled). Example: "2024-01-21T10:00:00Z"
data[].google_sheet_fieldsobject | nullGoogle Sheets integration configuration (null if not configured). Example: null
data[].ftp_fieldsobject | nullFTP integration configuration (null if not configured). Example: null
data[].s3_fieldsobject | nullAWS S3 integration configuration (null if not configured). Example: null
data[].webhook_fieldsobject | nullWebhook integration configuration (null if not configured). Example: null
data[].schedulestring | nullCron expression for scheduled runs (null if not scheduled). Example: "0 10 * * *"
data[].schedule_timestringHuman-readable schedule description. Example: "Daily at 10:00 AM"
data[].download_urlstring | nullTemporary 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
{ "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 }