> ## 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.

# Configure Squid Chain

> Chain two crawlers together so results from one automatically feed into another

Crawler chaining lets you connect two squids so that when a run on the **source squid** completes, its results are automatically extracted and queued as tasks on a **target squid**, triggering a new run downstream.

**Example use case:** Run a Google Maps Leads scrape to collect place URLs, then automatically pass those URLs into a Google Maps Reviews scrape — without any manual intervention.

<Note>
  Chains are limited to a maximum depth of 3 squids. A squid can only have one outgoing chain at a time.
</Note>

## How it works

1. You configure a chain on a source squid, specifying the target crawler and a `field_map`
2. When a run on the source squid completes with a status of **`DONE`**, the scheduler extracts the mapped fields from its results
3. Those values are queued as tasks on the target squid (auto-created on first trigger if it doesn't exist yet)
4. If `autostart` is `true`, a new run starts immediately on the target squid

<Warning>
  The chain is only triggered when the source run reaches a status of `DONE`. Runs that end with `ERROR` or any other status will not trigger the downstream chain.
</Warning>

## Path Parameters

<ParamField path="id" type="string" required>
  Hash ID of the source squid. Example: `"e86b29c032024b66aff529e1d43c2bd7"`
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Your API authentication token. Value: `Token YOUR_API_KEY`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be application/json. Value: `application/json`
</ParamField>

## Request Body

<ParamField body="target_module_id" type="string" required>
  Hash ID of the target crawler. Use `GET /v1/crawlers` to find it. Example: `"9a3f1c8b2e7d4a56f0e1b2c3d4e5f678"`
</ParamField>

<ParamField body="field_map" type="object" required>
  Maps a result field from the source crawler to an input parameter on the target crawler. Example: `{"url": "url"}` — passes the `url` field from source results as the `url` input on the target.
</ParamField>

<ParamField body="autostart" type="boolean">
  If `true`, the downstream run starts automatically when tasks are queued. If `false`, tasks are queued and the run is created as paused for manual review. Defaults to `true`.
</ParamField>

<ParamField body="cluster_name" type="string">
  Custom name for the auto-created target squid. If omitted, defaults to `"{Crawler Name} (N) (chained)"`.
</ParamField>

<ParamField body="cluster_concurrency" type="integer">
  Concurrency to apply to the auto-created target squid. Defaults to `1`.
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique chain config identifier.
</ResponseField>

<ResponseField name="target_module" type="object">
  Details of the target crawler.

  <Expandable title="target_module fields">
    <ResponseField name="id" type="string">Crawler hash ID</ResponseField>
    <ResponseField name="public_name" type="string">Human-readable crawler name</ResponseField>
    <ResponseField name="max_concurrency" type="integer">Maximum concurrency supported by this crawler</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="target_cluster" type="object | null">
  The auto-created target squid. `null` until the first chain trigger fires.
</ResponseField>

<ResponseField name="field_map" type="object">
  The configured field mapping.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the chain is currently active.
</ResponseField>

<ResponseField name="autostart" type="boolean">
  Whether downstream runs start automatically.
</ResponseField>

<ResponseField name="cluster_name" type="string | null">
  Configured name for the target squid.
</ResponseField>

<ResponseField name="cluster_concurrency" type="integer | null">
  Configured concurrency for the target squid.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the chain was configured.
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.lobstr.io/v1/squids/e86b29c032024b66aff529e1d43c2bd7/chain" \
    -H "Authorization: Token YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "target_module_id": "9a3f1c8b2e7d4a56f0e1b2c3d4e5f678",
      "field_map": {"url": "url"},
      "autostart": true,
      "cluster_name": "Reviews (chained)",
      "cluster_concurrency": 3
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.lobstr.io/v1/squids/e86b29c032024b66aff529e1d43c2bd7/chain"
  headers = {
      "Authorization": "Token YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "target_module_id": "9a3f1c8b2e7d4a56f0e1b2c3d4e5f678",
      "field_map": {"url": "url"},
      "autostart": True,
      "cluster_name": "Reviews (chained)",
      "cluster_concurrency": 3
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

## Response

```json 201 theme={null}
{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "target_module": {
    "id": "9a3f1c8b2e7d4a56f0e1b2c3d4e5f678",
    "public_name": "Google Maps Reviews Scraper",
    "name": "googlemapreviews_matrix",
    "max_concurrency": 10
  },
  "target_cluster": null,
  "field_map": {"url": "url"},
  "is_active": true,
  "autostart": true,
  "cluster_name": "Reviews (chained)",
  "cluster_concurrency": 3,
  "created_at": "2026-04-28T10:00:00Z"
}
```

```json 400 theme={null}
{
  "error": "field_map is required and must be a dict."
}
```

```json 409 theme={null}
{
  "error": "This squid already has a chain configured."
}
```

```json 422 theme={null}
{
  "error": "Chain depth limit of 3 reached."
}
```