Skip to main content
GET
/
v1
/
squids
/
{squid_hash}
Get Squid Details
curl --request GET \
  --url https://api.lobstr.io/v1/squids/{squid_hash} \
  --header 'Authorization: <authorization>'
{
  "id": "<string>",
  "name": "<string>",
  "created_at": "<string>",
  "is_active": true,
  "is_ready": true,
  "crawler": "<string>",
  "crawler_name": "<string>",
  "icon": "<string>",
  "concurrency": 123,
  "params": {},
  "to_complete": true,
  "message": "<string>",
  "params.max_results": 123,
  "params.max_unique_results_per_run": 123,
  "params.fetch_since": "<string>",
  "params.fetch_since_timezone": "<string>",
  "params.max_date": "<string>",
  "params.functions": {},
  "last_run_status": "<string>",
  "last_run": "<string>",
  "last_run_at": "<string>",
  "last_run_done_reason": "<string>",
  "total_runs": 123,
  "next_launch_at": {},
  "download_url": {},
  "export_runs": true,
  "export_unique_results": true,
  "no_line_breaks": true,
  "google_sheet_fields": {},
  "ftp_fields": {},
  "s3_fields": {},
  "webhook_fields": {},
  "slack_fields": {},
  "schedule": {},
  "schedule_time": "<string>",
  "email": "<string>",
  "notifications": true,
  "notifications_params": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.lobstr.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
id
string
Unique identifier for the squid. Example: "c106a44a98044ef18acc59986ae10967"
​
name
string
Display name of the squid. Example: "Google Maps (1)"
​
created_at
string
Timestamp when the squid was created. Example: "2024-01-15T10:30:00Z"
​
is_active
boolean
Whether the squid is active and can run. Example: true
​
is_ready
boolean
Whether the squid has tasks and is ready to run. Example: true
​
crawler
string
Unique identifier of the associated crawler. Example: "4734d096159ef05210e0e1677e8be823"
​
crawler_name
string
Display name of the crawler. Example: "Google Maps Search Export"
​
icon
string
URL to the crawler’s icon image. Example: "https://cdn.lobstr.io/icons/google-maps.png"
​
concurrency
integer
Number of concurrent tasks the squid runs. Example: 2
​
params
object
Crawler-specific parameter configuration object. Example: {}
​
to_complete
boolean
Whether to stop after completing all tasks. Example: false
​
message
string
Important operational information or error messages. Example: ""

​
Common Parameters

The params object contains crawler-specific settings. Most crawlers share these common parameters:
​
params.max_results
integer
Maximum results per task. null = unlimited. Example: 200
​
params.max_unique_results_per_run
integer
Maximum unique results across all tasks in a run. null = unlimited. Example: null
​
params.fetch_since
string
Stop 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_timezone
string
Timezone 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_date
string
Deprecated — stop scraping when items older than this date are reached. Use fetch_since instead. Example: null
​
params.functions
object
Optional add-on features. Each key is a boolean toggle. Enabling incurs extra credits per row. Example: {"details": true}

​
Run Status & History Fields

​
last_run_status
string
Current status of the most recent run (DONE, RUNNING, ERROR, etc.). Example: "DONE"
​
last_run
string
ID of the most recent run. Example: "abc123"
​
last_run_at
string
Timestamp of the last execution. Example: "2024-01-20T15:45:00Z"
​
last_run_done_reason
string
Why the run ended (tasks_done, credits_exhausted, user_stopped, error). Example: "tasks_done"
​
total_runs
integer
Total number of runs executed for this squid. Example: 5
​
next_launch_at
string | null
Scheduled time for next run (null if not scheduled). Example: "2024-01-21T10:00:00Z"

​
Export & Download Fields

​
download_url
string | null
Temporary signed URL to download latest results (expires after a time period). Example: null
​
export_runs
boolean
Whether to export runs. Example: true
​
export_unique_results
boolean
Only export unique results, removing duplicates. Example: true
​
no_line_breaks
boolean
Remove newlines from exported data. Example: false

​
Integration Configuration Fields

​
google_sheet_fields
object | null
Google Sheets integration configuration (null if not configured). Contains is_active flag. Example: null
​
ftp_fields
object | null
SFTP delivery settings (null if not configured). Contains is_active flag. Example: null
​
s3_fields
object | null
Amazon S3 export configuration (null if not configured). Contains is_active flag. Example: null
​
webhook_fields
object | null
Webhook notifications setup (null if not configured). Contains is_active flag. Example: null
​
slack_fields
object | null
Slack integration settings (null if not configured). Contains is_active flag. Example: null

​
Scheduling Fields

​
schedule
object | null
Cron schedule object with expression and timezone (null if not scheduled). Example: null
​
schedule_time
string
Next scheduled execution time in human-readable format. Example: "Daily at 10:00 AM"

​
Notification Fields

​
email
string
Email address for notifications. Example: "user@example.com"
​
notifications
boolean
Whether notifications are enabled. Example: true
​
notifications_params
object
Notification configuration object containing run_notify setting (on_success, on_error, or null). Example: {"run_notify": "on_success"}

​
Headers

​
Authorization
string
required
Your API authentication token. Value: Token YOUR_API_KEY

​
Query Parameters

​
squid_hash
string
required
The 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

200
{
  "id": "c106a44a98044ef18acc59986ae10967",
  "created_at": "2025-02-25T09:01:13.575329",
  "name": "my-cool-squid",
  "is_ready": true,
  "is_active": true,
  "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
}