Get Squid Details
Retrieve comprehensive details about a specific squid including configuration, status, and integrations
https://api.lobstr.io/v1/squids/{squid_hash}This endpoint retrieves comprehensive details about a specific squid, including its configuration settings, operational status, integration options, run statistics, and associated crawler information.
Core Information Fields
idstringUnique identifier for the squid. Example: "c106a44a98044ef18acc59986ae10967"
namestringDisplay name of the squid. Example: "Google Maps (1)"
created_atstringTimestamp when the squid was created. Example: "2024-01-15T10:30:00Z"
created_viastring | nullWhich surface created this squid — "api", "sdk", "cli", or "mcp". null for squids created in the dashboard. The dashboard shows this as a badge next to the squid's name. Example: "api"
is_activebooleanWhether the squid is active and can run. Example: true
deactivation_reasonstring | nullWhy the squid was deactivated, or null while it is active. Example: null
is_readybooleanWhether the squid has tasks and is ready to run. Example: true
crawlerstringUnique identifier of the associated crawler. Example: "4734d096159ef05210e0e1677e8be823"
crawler_namestringDisplay name of the crawler. Example: "Google Maps Search Export"
iconstringURL to the crawler's icon image. Example: "https://cdn.lobstr.io/icons/google-maps.png"
concurrencyintegerNumber of concurrent tasks the squid runs. Example: 2
accountsarray | nullConnected platform accounts linked to this squid. Empty (or null) for crawlers that need no account — see Link Account to Squid. Example: []
auto_verify_emailsbooleanWhether found email addresses are verified automatically. Set it under the squid's advanced settings; only applies to crawlers whose has_email_verification is true. Example: false
paramsobjectCrawler-specific parameter configuration object. Example: {}
to_completebooleanWhether to stop after completing all tasks. Example: false
messagestringImportant operational information or error messages. Example: ""
Common Parameters
The params object contains crawler-specific settings. Most crawlers share these common parameters:
params.max_resultsintegerMaximum results per task. null = unlimited. Example: 200
params.max_unique_results_per_runintegerMaximum unique results across all tasks in a run. null = unlimited. Example: null
params.fetch_sincestringStop scraping when items older than this threshold are reached. Accepts a relative duration (24h, 7d, 2w) or an absolute date (YYYY-MM-DD HH:MM). Example: "7d"
params.fetch_since_timezonestringTimezone for interpreting an absolute fetch_since date (e.g. "Europe/Paris"). Only applies when fetch_since is an absolute date — ignored for relative values like "24h" or "7d". Example: "Europe/Paris"
params.max_datestringDeprecated — stop scraping when items older than this date are reached. Use fetch_since instead. Example: null
params.functionsobjectOptional add-on features. Each key is a boolean toggle. Enabling incurs extra credits per row. Example: {"details": true}
Run Status & History Fields
last_run_statusstringCurrent status of the most recent run (DONE, RUNNING, ERROR, etc.). Example: "DONE"
last_runstringID of the most recent run. Example: "abc123"
last_run_atstringTimestamp of the last execution. Example: "2024-01-20T15:45:00Z"
last_run_done_reasonstringWhy the run ended (tasks_done, credits_exhausted, user_stopped, error). Example: "tasks_done"
total_runsintegerTotal number of runs executed for this squid. Example: 5
next_launch_atstring | nullScheduled time for next run (null if not scheduled). Example: "2024-01-21T10:00:00Z"
Export & Download Fields
download_urlstring | nullTemporary signed URL to download latest results (expires after a time period). Example: null
export_runsbooleanWhether to export runs. Example: true
export_unique_resultsbooleanOnly export unique results, removing duplicates. Example: true
no_line_breaksbooleanRemove newlines from exported data. Example: false
Integration Configuration Fields
google_sheet_fieldsobject | nullGoogle Sheets integration configuration (null if not configured). Contains is_active flag. Example: null
ftp_fieldsobject | nullSFTP delivery settings (null if not configured). Contains is_active flag. Example: null
s3_fieldsobject | nullAmazon S3 export configuration (null if not configured). Contains is_active flag. Example: null
webhook_fieldsobject | nullWebhook notifications setup (null if not configured). Contains is_active flag. Example: null
slack_fieldsobject | nullSlack integration settings (null if not configured). Contains is_active flag. Example: null
Scheduling Fields
scheduleobject | nullCron schedule object with expression and timezone (null if not scheduled). Example: null
schedule_timestringNext scheduled execution time in human-readable format. Example: "Daily at 10:00 AM"
Notification Fields
emailstringEmail address for notifications. Example: "user@example.com"
notificationsbooleanWhether notifications are enabled. Example: true
notifications_paramsobjectNotification configuration object containing run_notify setting (on_success, on_error, or null). Example: {"run_notify": "on_success"}
Headers
AuthorizationstringheaderrequiredYour API authentication token. Value: Token YOUR_API_KEY
Path Parameters
squid_hashstringpathrequiredThe unique identifier (hash) of the squid. Example: c106a44a98044ef18acc59986ae10967
Check 'is_ready' before starting a run. If false, you need to add tasks to the squid first.
The 'message' field contains important operational information or error messages. Check this if a squid isn't behaving as expected.
The 'download_url' is a temporary signed URL that expires. Download results promptly or generate a new URL by re-fetching squid details.
Use 'last_run_done_reason' to understand why a run stopped. Common reasons: tasks_done, credits_exhausted, user_stopped, error.
Integration fields (google_sheet_fields, etc.) show 'is_active: true' if enabled. Configure these to automate result delivery.
Use fetch_since to stop scraping when older items are reached. Supports relative durations (24h, 7d, 2w) and absolute dates (YYYY-MM-DD HH:MM). When using an absolute date, set fetch_since_timezone to interpret it in the correct timezone (e.g. "Europe/Paris"). Replaces the older hours_back and max_date parameters.
Code Examples
curl -X GET "https://api.lobstr.io/v1/squids/c106a44a98044ef18acc59986ae10967" \ -H "Authorization: Token YOUR_API_KEY"
Response
{ "id": "c106a44a98044ef18acc59986ae10967", "created_at": "2025-02-25T09:01:13.575329", "created_via": "api", "name": "my-cool-squid", "is_ready": true, "is_active": true, "deactivation_reason": null, "concurrency": 1, "params": { "country": "United States", "ratings": "Any rating", "language": "English (United States)", "max_results": 20, "functions": { "fetch_business_images": false, "collect_business_details": false, "extract_emails_from_website": false } }, "download_url": "https://s3.eu-west-1.amazonaws.com/api.lobstr.io/temporary/lobstrc106a44a98044ef18acc59986ae10967/eebce7802e7740979a0b8450de10c99e.csv.csv?...", "email": "user@example.com", "schedule": null, "schedule_time": null, "no_line_breaks": true, "export_runs": true, "export_unique_results": true, "notifications": true, "notifications_params": { "run_notify": null }, "to_complete": false, "google_sheet_fields": { "url": "https://docs.google.com/spreadsheets/d/...", "append": false, "is_active": false }, "ftp_fields": { "host": "localhost", "port": 22, "is_active": false }, "s3_fields": { "bucket": null, "is_active": false }, "webhook_fields": { "url": "https://example.com/webhook", "is_active": false }, "crawler": "4734d096159ef05210e0e1677e8be823", "crawler_name": "Google Maps Search Export", "last_run_status": "DONE", "total_runs": 1, "next_launch_at": null, "last_run": "eebce7802e7740979a0b8450de10c99e", "last_run_at": "2025-03-05T09:27:17.012423", "last_run_done_reason": "tasks_done", "last_run_is_done": true, "is_public": true }