---
title: "Signaliz Flow"
method: POST
path: "/functions/v1/signaliz-flow-trigger"
tags: ["Signaliz Flow"]
---

# Signaliz Flow

`POST /functions/v1/signaliz-flow-trigger`

## Request

- Base URL: `https://api.signaliz.com`
- URL: `https://api.signaliz.com/functions/v1/signaliz-flow-trigger`
- Auth: HTTP bearer

Start a signal-to-review workflow immediately, or retrieve an existing run with run_id. Builder costs 1 credit ($0.01) per company; Scale and Enterprise include unlimited Flow. Use lookback_days to set the maximum evidence age; Signaliz selects Company Signal acquisition internally. Nothing sends from Flow.

## Headers

- `Idempotency-Key` string

## Request body

- union: Start Signaliz Flow immediately, or read an existing workspace-owned run with run_id. Builder costs 1 credit ($0.01) per company; Scale and Enterprise include unlimited Flow. Flow carries discovered signal evidence through people, email verification, and review-ready copy without sending outreach.
  - object
    - `run_id` string, required: Read the durable status and customer-safe result for an existing Flow run. This never dispatches work.
    - `signal_query` string
    - `campaign_offer` string
    - `signal_limit` integer
    - `lookback_days` integer: Maximum age of source-backed company evidence. Signaliz derives the internal date window.
    - `icp_context` string
    - `people_titles` string[]
    - `people_per_company` integer
    - `copy_research_prompt` string
    - `approval_required` boolean: Keep completed copy in review. Flow never sends outreach.
    - `flow_id` string
    - `idempotency_key` string: Stable retry key. The Idempotency-Key HTTP header is also supported.
  - object
    - `run_id` string: Read the durable status and customer-safe result for an existing Flow run. This never dispatches work.
    - `signal_query` string, required
    - `campaign_offer` string, required
    - `signal_limit` integer
    - `lookback_days` integer: Maximum age of source-backed company evidence. Signaliz derives the internal date window.
    - `icp_context` string
    - `people_titles` string[]
    - `people_per_company` integer
    - `copy_research_prompt` string
    - `approval_required` boolean: Keep completed copy in review. Flow never sends outreach.
    - `flow_id` string
    - `idempotency_key` string: Stable retry key. The Idempotency-Key HTTP header is also supported.

## Response `200`

A durable Flow status was returned.

- SignalizFlowResult
  - `success` boolean
  - `status` string: PLANNED or TRIGGERED for a new request, otherwise the durable pipeline run status.
  - `flow_id` string
  - `run_id` string
  - `status_endpoint` string
  - `message` string
  - `result` object, nullable: Customer-safe durable Flow checkpoints and review-ready outcomes.
  - `credits_charged` number
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `idempotency_key` string
  - `idempotency_replayed` boolean

## Other responses

- `202`: Flow was queued. Poll this same endpoint with the returned run_id.
- `400`: Invalid Flow input.
- `402`: Builder credit balance is empty or insufficient for this Flow run.
- `403`: AUTH_002: starting Flow requires Builder or higher and a write-capable Signaliz scope. Read-only credentials may read an existing run.
- `404`: The Flow run was not found in this workspace.
- `409`: The idempotency key is in progress, conflicted, or could not be safely recovered.
- `429`: Rate limited. Retry after the indicated delay.
- `502`: Flow could not be queued.

---

[API](https://skmtc.dev/signaliz/apis/signaliz-api.md) · [All operations](https://skmtc.dev/signaliz/apis/signaliz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signaliz/apis/signaliz-api/revisions/53cb64feddad?raw)