---
title: "Execute a workflow asynchronously"
method: POST
path: "/v1/workflows/{id}/run"
tags: ["Workflows"]
---

# Execute a workflow asynchronously

`POST /v1/workflows/{id}/run`

## Request

- Base URL: `https://api.paymongo.com`
- URL: `https://api.paymongo.com/v1/workflows/{id}/run`
- Auth: none required

Queues a workflow execution request for asynchronous processing. Returns immediately with status 'queued'. Use GET /v1/instances to check execution status.

## Path parameters

- `id` string, required

## Headers

- `Organization-Id` string, required
- `Idempotency-Key` string, required

## Request body

- ExecuteWorkflowRequestDTO
  - `input` object: Workflow input data (JSON object, required and validated explicitly)
  - `reference` ReferenceDTO
    - `external_id` string
    - `source` string

## Response `202`

Workflow queued successfully

- ExecuteWorkflowResponseDTO
  - `internal` boolean: Whether execution is internal (superuser only)
  - `livemode` boolean: Whether execution is in live mode
  - `message` string: Human-readable message
  - `message_id` string: Queue message ID for tracking
  - `queued_at` string: ISO 8601 timestamp when queued
  - `status` string: Execution status (always 'queued' for async execution)
  - `workflow_id` string: ID of the workflow definition

## Other responses

- `400`: missing_idempotency_key if the header is absent, invalid_idempotency_key if it is malformed, missing_organization_id or invalid_request_body otherwise
- `401`: authentication_failed, missing_authorization_header, unsupported_auth_method or jwt_signature_invalid when the credential is missing, malformed or rejected; accountid_identity_required when a superuser or service-to-service caller sends the Account-ID header
- `404`: workflow_not_found, the workflow is not found in this account and mode
- `409`: workflow_manual_run_not_allowed, the workflow has an active trigger and runs only from it
- `413`: workflow_input_too_large, the queued run message would exceed the queue's size limit
- `422`: idempotency_key_reuse, the key was already used for a request with a different workflow, input or reference
- `500`: Failed to queue workflow execution; invalid_configuration or accountid_delegation_failed when an Account-ID header is present
- `502`: accountid_relationship_lookup_failed or accountid_account_lookup_failed when an upstream service does not answer
- `503`: queue_failed, the run could not be queued; upstream_unavailable when an upstream service does not answer
- `504`: queue_timeout, queuing the run timed out; service_timeout when the request exceeds its deadline

---

[API](https://skmtc.dev/paymongo/apis/workflow.md) - [All operations](https://skmtc.dev/paymongo/apis/workflow/llms.txt) - [OpenAPI document](https://skmtc.dev/paymongo/apis/workflow/revisions/859719cfffa2?raw)