---
title: "Start workflow execution"
method: POST
path: "/workflows/{workflow_id}/executions"
tags: ["Workflows"]
---

# Start workflow execution

`POST /workflows/{workflow_id}/executions`

Start a new execution of a workflow asynchronously. The workflow will begin processing in the background.

You'll receive a 202 Accepted response with a tracking_id immediately. Use this tracking_id to:
- Poll GET /workflow_executions with tracking_id filter to check status
- Correlate execution events with your own systems

The execution will fail if:
- The workflow is not in 'active' status
- Required phone_number is missing or invalid
- The workflow definition is malformed

Use cases:
- Start workflow from external trigger (API, webhook, scheduled job)
- Test workflow with specific initial variables
- Retry failed execution with same parameters

**Burst rate limit**: This endpoint has an additional per-workflow burst limiter on top of the general platform API rate limits.
The burst counter is scoped by API key and workflow ID and resets every second.
- `legacy` / `free`: 5 requests per second
- `pro`: 15 requests per second
- `enterprise` / `platform`: 30 requests per second

Successful responses include `X-Burst-RateLimit-Limit` and `X-Burst-RateLimit-Remaining` headers.
If the burst limit is exceeded, the API returns `429 Too Many Requests` with `Retry-After: 1`.

## Request body

- WorkflowExecutionCreateRequest — Request to start a new workflow execution. Executions are processed asynchronously - you'll receive a tracking_id immediately and can poll for results using GET /workflow_executions/{id}.
  - `workflow_execution` object, required
    - `phone_number` string, required — E.164 formatted phone number for the conversation participant (e.g., '+14155552671'). This number will be normalized and used for conversation routing.
    - `phone_number_id` string — WhatsApp phone number identifier to use for sending messages. Use this to specify which WhatsApp Business number should handle the conversation. Preferred over whatsapp_config_id.
    - `whatsapp_config_id` integer — [DEPRECATED] Internal WhatsApp configuration ID. Use phone_number_id instead. This field is maintained for backward compatibility but may be removed in future versions.
    - `variables` object — Initial user-defined variables available to the workflow (key-value pairs). These variables can be accessed and modified throughout workflow execution using variable syntax (e.g., {{user.name}}).
    - `context` object — Additional contextual data passed to the workflow but not treated as user variables. Use this for metadata or system-specific information that shouldn't be part of the variable namespace.
    - `initial_data` object — Custom payload passed to the workflow's first step. Structure depends on the workflow's initial node configuration. Use this for complex initialization data.

## Response `202`

Workflow execution queued successfully (processing in background)

- WorkflowExecutionCreateAcceptedResponse — Async workflow execution initiation response (HTTP 202)
  - `data` WorkflowExecutionCreateAccepted, required — Async response returned when workflow execution is successfully queued (HTTP 202 Accepted). The execution will begin processing in the background. Use the id to retrieve execution details or the tracking_id to monitor progress.
    - `message` string, required — Confirmation message
    - `workflow_id` string, uuid, required — ID of the workflow being executed
    - `id` string, uuid, required — Unique execution identifier. Use this to retrieve execution details via GET /workflow_executions/{id} or to resume waiting executions via POST /workflow_executions/{id}/resume.
    - `tracking_id` string, uuid, required — Unique identifier for tracking this execution. Use this to query execution status via GET /workflow_executions (filter by tracking_id) or to correlate execution events with external systems.

## Other responses

- `401` — Missing or invalid API key
- `404` — Resource not found
- `422` — Request validation failed
- `429` — Workflow execution burst rate limit exceeded

---

[API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)