> For the complete documentation index, see [llms.txt](https://docs.waterflai.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.waterflai.ai/api-reference/asynchronous-execution.md).

# Asynchronous Execution

## Start Asynchronous Execution

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Waterflai Public API","version":"v1"},"servers":[{"url":"https://api.waterflai.ai","description":"Production Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your secret API key."}},"schemas":{"ExecutionRequest":{"type":"object","properties":{"input_data":{"type":"object","description":"A JSON object containing the input variables for the Chatflow or Workflow. The keys should match the names of the input nodes.","additionalProperties":true}}},"AsyncExecutionStartResponse":{"type":"object","properties":{"execution_id":{"type":"string","description":"The unique identifier for this execution job."},"status_url":{"type":"string","format":"uri","description":"The URL to poll for the execution status."},"stream_url":{"type":"string","format":"uri","description":"The URL to stream real-time progress."},"cancel_url":{"type":"string","format":"uri","description":"The URL to cancel the execution."}}},"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"A human-readable description of the error."}}}},"responses":{"UnauthorizedError":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/executions/{chatbot_id}/async":{"post":{"summary":"Start Asynchronous Execution","description":"Starts an asynchronous execution of a published Chatbot (Chatflow or Workflow). This is ideal for long-running tasks.\nThe 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.","tags":["Asynchronous Execution"],"parameters":[{"name":"chatbot_id","in":"path","required":true,"description":"The unique identifier of the Chatbot to execute.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionRequest"}}}},"responses":{"202":{"description":"The execution has been accepted for processing. The response body contains details to track the job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncExecutionStartResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get Execution Status

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Waterflai Public API","version":"v1"},"servers":[{"url":"https://api.waterflai.ai","description":"Production Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your secret API key."}},"schemas":{"ExecutionJobResponse":{"type":"object","properties":{"execution_id":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"]},"progress":{"type":"number","format":"float","description":"A value from 0.0 to 100.0 indicating the completion percentage."},"current_node":{"type":"string","nullable":true,"description":"The ID of the node currently being executed."},"completed_nodes":{"type":"integer"},"total_nodes":{"type":"integer"},"final_output":{"type":"object","nullable":true,"additionalProperties":true,"description":"The final result of the execution, available when status is `COMPLETED`."},"error_message":{"type":"string","nullable":true,"description":"Details about the error, available when status is `FAILED`."},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"retry_count":{"type":"integer"},"execution_source":{"type":"string","enum":["CHATBOT","STUDIO","API"]},"is_temporary":{"type":"boolean"},"cleanup_after":{"type":"string","format":"date-time","nullable":true}}},"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"A human-readable description of the error."}}}},"responses":{"UnauthorizedError":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/executions/{execution_id}":{"get":{"summary":"Get Execution Status","description":"Retrieves the current status and result of a specific asynchronous execution.\nYou should poll this endpoint to check the job's progress. Once the `status` is `COMPLETED`, the `final_output` field will contain the result.","tags":["Asynchronous Execution"],"parameters":[{"name":"execution_id","in":"path","required":true,"description":"The unique identifier of the execution job.","schema":{"type":"string"}}],"responses":{"200":{"description":"The current state of the execution job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionJobResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Cancel Asynchronous Execution

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

```json
{"openapi":"3.0.3","info":{"title":"Waterflai Public API","version":"v1"},"servers":[{"url":"https://api.waterflai.ai","description":"Production Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your secret API key."}},"schemas":{"ExecutionCancelResponse":{"type":"object","properties":{"execution_id":{"type":"string"},"cancelled":{"type":"boolean","description":"True if the cancellation was successful."},"message":{"type":"string","description":"A confirmation message."},"previous_status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED"],"description":"The status of the job before cancellation was attempted."}}},"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"A human-readable description of the error."}}}},"responses":{"UnauthorizedError":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/executions/{execution_id}":{"delete":{"summary":"Cancel Asynchronous Execution","description":"Cancels a `PENDING` or `RUNNING` execution.\nCompleted, failed, or already cancelled jobs cannot be cancelled again.","tags":["Asynchronous Execution"],"parameters":[{"name":"execution_id","in":"path","required":true,"description":"The unique identifier of the execution job to cancel.","schema":{"type":"string"}}],"responses":{"200":{"description":"The cancellation request was successfully processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionCancelResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Stream Asynchronous Execution Progress

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Waterflai Public API","version":"v1"},"servers":[{"url":"https://api.waterflai.ai","description":"Production Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your secret API key."}},"responses":{"UnauthorizedError":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"A human-readable description of the error."}}}}},"paths":{"/v1/executions/{execution_id}/stream":{"get":{"summary":"Stream Asynchronous Execution Progress","description":"Streams the real-time progress of a specific asynchronous execution via Server-Sent Events (SSE).\nThis provides a live feed of events like `node_started`, `node_completed`, and `execution_completed`. The stream closes automatically when the job finishes.","tags":["Asynchronous Execution"],"parameters":[{"name":"execution_id","in":"path","required":true,"description":"The unique identifier of the execution job.","schema":{"type":"string"}}],"responses":{"200":{"description":"A stream of events representing the real-time execution progress.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```