---
title: "Run one scoped pipeline job per state for a selection that spans states"
method: POST
path: "/api/v1/pipeline/trigger-multi"
tags: ["pipeline", "pipeline"]
---

# Run one scoped pipeline job per state for a selection that spans states

`POST /api/v1/pipeline/trigger-multi`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/pipeline/trigger-multi`
- Auth: API key in header `X-API-Key`

Fan a cross-state selection out into one ordinary scoped run per state.

Each leg goes through the same `POST /trigger` code path it would have taken
if you had picked that state by hand — same validation, same Run Manifest,
same per-entity COGS attribution, same concurrency lock.

**Partial success is the normal outcome, not an error.** A state whose lock
is held by the overnight harvest cannot start a second run, and silently
dropping it is how an operator comes to believe they enriched records they
did not. Every leg is reported with its own `status` and `job_id`; the call
fails (409 / 400) only when *nothing* started.

Scope with `entity_id` (IDs may span states — they are grouped) or `filters`
(no state clause; each leg adds its own). `limit` is per state; `pull` is
refused because it ignores record scope.

## Request body

- MultiStateTriggerRequest: Run one scoped pipeline job per state for a selection that spans states. Scope fields are inherited, so what the preview resolved is what this runs. Each state gets its own ordinary scoped run — own Job, own Run Manifest, own COGS attribution — launched in parallel.
  - `states` string[], nullable: Restrict the fan-out to these states. Omit to run every state the selection touches. It narrows, never widens: a state named here that the selection does not touch is simply absent from the result.
  - `limit` integer, nullable: PER-STATE cap, not a total — `limit=100` across 5 states runs up to 500 records. One shared budget would have to pick which state gets starved; capping each leg is the predictable reading of 'take 100 from each'.
  - `entity_id` string, nullable: Comma/space/newline-separated UUIDs or GLIDs that may span states. Grouped by state, one run per state. Mutually exclusive with `filters`.
  - `filters` object[], nullable: Filter expression, same shape as POST /api/v1/leads/browse, WITHOUT a state clause — the fan-out supplies each leg's own. Mutually exclusive with `entity_id`.
  - `include_non_operating` boolean: Only meaningful with `filters`. Mirrors Browse's own default so the per-state counts match the number on the button the operator pressed — see `TriggerRequest.include_non_operating`.
  - `include_existing` boolean: Only meaningful with `filters`. See `TriggerRequest.include_existing`.
  - `include_registrations` boolean: Deprecated alias of include_existing (kept one release so saved requests resolve).
  - `stages` union: Pipeline stages to run in EVERY state leg. Same vocabulary as POST /trigger. `pull` is refused here — and because `all` contains `pull`, the default is refused too: a fan-out must name the stages it is running.
    - string
    - string[]
  - `gapfill_force` boolean: Forced paid re-dip, applied to every leg. Same rules as POST /trigger.
  - `force_recompute` boolean: Force free stages to recompute in every leg. Same rules as POST /trigger.

## Response `202`

Successful Response

- MultiStateTriggerResponse
  - `started` integer, required
  - `skipped` integer, required
  - `stages` string[], required: The expanded stage list every started leg is running.
  - `legs` MultiStateLeg[], required
    - `state` string, required
    - `matched` integer, required: Records the selection resolved to in this state.
    - `status` string, required: `started` (a job is running) · `queued` (accepted, waiting for a worker — starts on its own) · `blocked` (another run holds this state's lock — re-run when it clears) · `unavailable` (records but no pipeline config) · `skipped` (nothing runnable) · `error` (launch failed, nothing ran).
    - `detail` string, nullable
    - `job_id` string, nullable
    - `status_url` string, nullable
    - `task_arn` string, nullable
  - `capacity_note` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)