# 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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.waterflai.ai/api-reference/asynchronous-execution.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.