Get Squid Details

curl --request GET \
  --url https://api.lobstr.io/v1/squids/{squid_hash} \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.lobstr.io/v1/squids/{squid_hash}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.lobstr.io/v1/squids/{squid_hash}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lobstr.io/v1/squids/{squid_hash}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lobstr.io/v1/squids/{squid_hash}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.lobstr.io/v1/squids/{squid_hash}")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lobstr.io/v1/squids/{squid_hash}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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": {}
}

GET

squids

{squid_hash}

Get Squid Details

curl --request GET \
  --url https://api.lobstr.io/v1/squids/{squid_hash} \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.lobstr.io/v1/squids/{squid_hash}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.lobstr.io/v1/squids/{squid_hash}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lobstr.io/v1/squids/{squid_hash}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lobstr.io/v1/squids/{squid_hash}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.lobstr.io/v1/squids/{squid_hash}")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lobstr.io/v1/squids/{squid_hash}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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": {}
}

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

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

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"

import requests

squid_id = "c106a44a98044ef18acc59986ae10967"
url = f"https://api.lobstr.io/v1/squids/{squid_id}"
headers = {
    "Authorization": "Token YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
squid = response.json()

print(f"Squid: {squid['name']}")
print(f"Status: {'Active' if squid['is_active'] else 'Inactive'}")
print(f"Ready: {squid['is_ready']}")
print(f"\nRun Statistics:")
print(f"  Total Runs: {squid['total_runs']}")
print(f"  Last Status: {squid['last_run_status']}")
print(f"  Last Run At: {squid['last_run_at']}")

if squid.get('download_url'):
    print(f"\nDownload URL available: {squid['download_url'][:50]}...")

print(f"\nIntegrations:")
print(f"  Google Sheets: {squid['google_sheet_fields']['is_active']}")
print(f"  FTP: {squid['ftp_fields']['is_active']}")
print(f"  S3: {squid['s3_fields']['is_active']}")
print(f"  Webhook: {squid['webhook_fields']['is_active']}")

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
}

List Squids Empty Squid

​Core Information Fields

​Common Parameters

​Run Status & History Fields

​Export & Download Fields

​Integration Configuration Fields

​Scheduling Fields

​Notification Fields

​Headers

​Query Parameters

​Code Examples

​Response

Core Information Fields

Common Parameters

Run Status & History Fields

Export & Download Fields

Integration Configuration Fields

Scheduling Fields

Notification Fields

Headers

Query Parameters

Code Examples

Response