Asynchronous Execution

Start Asynchronous Execution

post

Starts an asynchronous execution of a published Chatbot (Chatflow or Workflow). This is ideal for long-running tasks. The API queues the job and immediately returns an execution_id and tracking URLs, allowing you to check the status later without keeping the connection open.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Your secret API key.

Path parameters

chatbot_idstringRequired

The unique identifier of the Chatbot to execute.

Body

application/json

Responses

202

The execution has been accepted for processing. The response body contains details to track the job.

application/json

401

API key is missing or invalid.

application/json

404

The requested resource was not found.

application/json

500

An unexpected error occurred on the server.

application/json

post

/v1/executions/{chatbot_id}/async

HTTPcURLJavaScriptPython

POST /v1/executions/{chatbot_id}/async HTTP/1.1
Host: api.waterflai.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "input_data": {
    "query": "What is Waterflai?",
    "user_id": "user-123"
  }
}

{
  "execution_id": "text",
  "status_url": "https://example.com",
  "stream_url": "https://example.com",
  "cancel_url": "https://example.com"
}

Get Execution Status

get

Retrieves the current status and result of a specific asynchronous execution. You should poll this endpoint to check the job's progress. Once the status is COMPLETED, the final_output field will contain the result.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Your secret API key.

Path parameters

execution_idstringRequired

The unique identifier of the execution job.

Responses

200

The current state of the execution job.

application/json

execution_idstringOptional

statusstring · enumOptionalPossible values:

progressnumber · floatOptional

A value from 0.0 to 100.0 indicating the completion percentage.

current_nodestring · nullableOptional

The ID of the node currently being executed.

completed_nodesintegerOptional

total_nodesintegerOptional

error_messagestring · nullableOptional

Details about the error, available when status is FAILED.

created_atstring · date-timeOptional

started_atstring · date-time · nullableOptional

completed_atstring · date-time · nullableOptional

retry_countintegerOptional

execution_sourcestring · enumOptionalPossible values:

is_temporarybooleanOptional

cleanup_afterstring · date-time · nullableOptional

401

API key is missing or invalid.

application/json

404

The requested resource was not found.

application/json

500

An unexpected error occurred on the server.

application/json

get

/v1/executions/{execution_id}

HTTPcURLJavaScriptPython

GET /v1/executions/{execution_id} HTTP/1.1
Host: api.waterflai.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "execution_id": "text",
  "status": "PENDING",
  "progress": 1,
  "current_node": "text",
  "completed_nodes": 1,
  "total_nodes": 1,
  "final_output": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "error_message": "text",
  "created_at": "2026-03-21T15:35:02.124Z",
  "started_at": "2026-03-21T15:35:02.124Z",
  "completed_at": "2026-03-21T15:35:02.124Z",
  "retry_count": 1,
  "execution_source": "CHATBOT",
  "is_temporary": true,
  "cleanup_after": "2026-03-21T15:35:02.124Z"
}

Cancel Asynchronous Execution

delete

Cancels a PENDING or RUNNING execution. Completed, failed, or already cancelled jobs cannot be cancelled again.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Your secret API key.

Path parameters

execution_idstringRequired

The unique identifier of the execution job to cancel.

Responses

200

The cancellation request was successfully processed.

application/json

execution_idstringOptional

cancelledbooleanOptional

True if the cancellation was successful.

messagestringOptional

A confirmation message.

previous_statusstring · enumOptional

The status of the job before cancellation was attempted.

Possible values:

401

API key is missing or invalid.

application/json

404

The requested resource was not found.

application/json

500

An unexpected error occurred on the server.

application/json

delete

/v1/executions/{execution_id}

HTTPcURLJavaScriptPython

DELETE /v1/executions/{execution_id} HTTP/1.1
Host: api.waterflai.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "execution_id": "text",
  "cancelled": true,
  "message": "text",
  "previous_status": "PENDING"
}

Stream Asynchronous Execution Progress

get

Streams the real-time progress of a specific asynchronous execution via Server-Sent Events (SSE). This provides a live feed of events like node_started, node_completed, and execution_completed. The stream closes automatically when the job finishes.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Your secret API key.

Path parameters

execution_idstringRequired

The unique identifier of the execution job.

Responses

200

A stream of events representing the real-time execution progress.

text/event-stream

stringOptionalExample: data: {"type": "progress_update", "progress": 50.0}

401

API key is missing or invalid.

application/json

404

The requested resource was not found.

application/json

500

An unexpected error occurred on the server.

application/json

get

/v1/executions/{execution_id}/stream

HTTPcURLJavaScriptPython

GET /v1/executions/{execution_id}/stream HTTP/1.1
Host: api.waterflai.ai
X-API-Key: YOUR_API_KEY
Accept: */*

data: {"type": "progress_update", "progress": 50.0}