Skip to content
Squid

Get Squid Details

Retrieve comprehensive details about a specific squid including configuration, status, and integrations

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

idstring

Unique identifier for the squid. Example: "c106a44a98044ef18acc59986ae10967"

namestring

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

created_atstring

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

created_viastring | null

Which 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_activeboolean

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

deactivation_reasonstring | null

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

is_readyboolean

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

crawlerstring

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

crawler_namestring

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

iconstring

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

concurrencyinteger

Number of concurrent tasks the squid runs. Example: 2

accountsarray | null

Connected platform accounts linked to this squid. Empty (or null) for crawlers that need no account — see Link Account to Squid. Example: []

auto_verify_emailsboolean

Whether 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

paramsobject

Crawler-specific parameter configuration object. Example: {}

to_completeboolean

Whether to stop after completing all tasks. Example: false

messagestring

Important operational information or error messages. Example: ""

Common Parameters

The params object contains crawler-specific settings. Most crawlers share these common parameters:

params.max_resultsinteger

Maximum results per task. null = unlimited. Example: 200

params.max_unique_results_per_runinteger

Maximum unique results across all tasks in a run. null = unlimited. Example: null

params.fetch_sincestring

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_timezonestring

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_datestring

Deprecated — stop scraping when items older than this date are reached. Use fetch_since instead. Example: null

params.functionsobject

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_statusstring

Current status of the most recent run (DONE, RUNNING, ERROR, etc.). Example: "DONE"

last_runstring

ID of the most recent run. Example: "abc123"

last_run_atstring

Timestamp of the last execution. Example: "2024-01-20T15:45:00Z"

last_run_done_reasonstring

Why the run ended (tasks_done, credits_exhausted, user_stopped, error). Example: "tasks_done"

total_runsinteger

Total number of runs executed for this squid. Example: 5

next_launch_atstring | null

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

Export & Download Fields

download_urlstring | null

Temporary signed URL to download latest results (expires after a time period). Example: null

export_runsboolean

Whether to export runs. Example: true

export_unique_resultsboolean

Only export unique results, removing duplicates. Example: true

no_line_breaksboolean

Remove newlines from exported data. Example: false

Integration Configuration Fields

google_sheet_fieldsobject | null

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

ftp_fieldsobject | null

SFTP delivery settings (null if not configured). Contains is_active flag. Example: null

s3_fieldsobject | null

Amazon S3 export configuration (null if not configured). Contains is_active flag. Example: null

webhook_fieldsobject | null

Webhook notifications setup (null if not configured). Contains is_active flag. Example: null

slack_fieldsobject | null

Slack integration settings (null if not configured). Contains is_active flag. Example: null

Scheduling Fields

scheduleobject | null

Cron schedule object with expression and timezone (null if not scheduled). Example: null

schedule_timestring

Next scheduled execution time in human-readable format. Example: "Daily at 10:00 AM"

Notification Fields

emailstring

Email address for notifications. Example: "user@example.com"

notificationsboolean

Whether notifications are enabled. Example: true

notifications_paramsobject

Notification configuration object containing run_notify setting (on_success, on_error, or null). Example: {"run_notify": "on_success"}

Headers

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Path Parameters

squid_hashstringpathrequired

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",
  "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
}