Task Polling
Retrieve results from async operations using the getResponse task. Learn how to poll for status updates and fetch completed results.
Introduction
Some operations like video generation require extended processing time. Instead of holding the connection open, you can set "deliveryMethod": "async" on your request to queue the task for asynchronous processing. You receive an acknowledgment immediately, then use the getResponse task to poll for status updates and retrieve the final result when ready.
Alternatively, you can use Webhooks to receive results via HTTP POST as soon as they are ready, without polling.
If you are using the JavaScript or Python SDK, async polling is handled automatically. You do not need to call getResponse directly. This page is relevant if you are integrating with the raw API.
How it works
When you call getResponse with a task UUID from an async operation, the system:
- Checks active operations and finds the running async task and all its generations.
- Returns the current status of each generation:
processing,success, orerror. - Provides results as they become available. Completed generations include their final outputs, so you can access partial results without waiting for everything to finish.
Implement exponential backoff when polling to avoid overwhelming the API. Start with 1-2 second intervals and gradually increase the delay between requests.
For tasks with predictable durations (like video generation), consider adding an initial delay before your first poll to reduce unnecessary requests.
Request
Our API always accepts an array of objects as input, where each object represents a specific task to be performed. The structure varies depending on the workflow and features used.
The following example shows the structure of a request object.
{
"taskType": "getResponse",
"taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada"
}Response
All requests return the same response format. Processing and successful generations appear in the data array, while failed generations are moved to the errors array.
{
"data": [
{
"taskType": "videoInference",
"taskUUID": "24cd5dff-cb81-4db5-8506-b72a9425f9d1",
"status": "processing"
},
{
"taskType": "videoInference",
"taskUUID": "24cd5dff-cb81-4db5-8506-b72a9425f9d1",
"status": "success",
"videoUUID": "b7db282d-2943-4f12-992f-77df3ad3ec71",
"videoURL": "https://im.runware.ai/video/ws/0.5/vi/b7db282d-2943-4f12-992f-77df3ad3ec71.mp4",
"cost": 0.18
}
],
"errors": [
{
"code": "timeoutProvider",
"status": "error",
"message": "The external provider did not respond within the timeout window. The request was automatically terminated.",
"documentation": "https://runware.ai/docs/platform/errors",
"taskUUID": "24cd5dff-cb81-4db5-8506-b72a9425f9d1"
}
]
}