---
title: cascades_trigger_workflow
description: Run a saved cascade for an applicant — i.e. start a decision.
canonical_url: "https://cascades.crscreditapi.com/docs/mcp/tools/cascades_trigger_workflow"
doc_version: "1.0.0"
last_updated: "2026-10-09T14:37:54Z"
source: docs/mcp/tools.json
---

# `cascades_trigger_workflow`

Run a saved cascade for an applicant — i.e. start a decision. POSTs to /api/v1/workflows/:id/trigger and returns the created execution, which starts in status "pending" (the run is async). After calling this, poll cascades_get_execution with the returned execution id until status is terminal (completed / failed / cancelled / awaiting_review). execution_mode defaults to "test", which also works on draft cascades; "live" requires a production-approved account and an active cascade and is otherwise rejected.

- **Access:** write
- **Scopes:** `executions:write`
- **REST operation:** `POST /api/v1/workflows/{id}/trigger` — [triggerWorkflow](https://cascades.crscreditapi.com/docs/api/workflows/trigger-workflow.md)

## Input schema

| Argument | Type | Required | Description |
|---|---|---|---|
| `workflow_id` | `integer` | yes | Workflow id. Only workflows owned by the token's account resolve; a foreign or deleted id returns `404`. |
| `payload` | `object` | no | The decision input. Put the subject under `applicant`; arbitrary nested fields are allowed and become the execution's `input_context`. Defaults to `{}` when omitted. |
| `execution_mode` | `string` | no | `test` uses synthetic vendor data and never bills; `live` requires production access and an active cascade. One of: `test`, `live`. |
| `external_reference` | `string` | no | Your correlation id for this run. Echoed on the execution and on every webhook event. |
| `environment` | `string` | no | Target environment: "prod" (default) or "dev". One of: `dev`, `prod`. |

## Example call

```json
{
  "name": "cascades_trigger_workflow",
  "arguments": {
    "workflow_id": 157,
    "execution_mode": "test",
    "payload": {
      "applicant": {
        "first_name": "Sandrx",
        "last_name": "Bowkey"
      }
    }
  }
}
```

## Example result

```json
{
  "data": {
    "id": 4821,
    "object": "execution",
    "workflow_id": 157,
    "status": "pending",
    "execution_mode": "test",
    "created_at": "2026-09-09T17:04:11Z"
  }
}
```

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.