Task Lifecycle Overview

This guide provides a conceptual overview of how tasks work in the Speech Platform 4 Virtual Appliance. It explains the high-level architecture and flow without implementation details. For hands-on usage with Python code and API specifics, please refer to the hands-on code guide.

Virtual Appliance employs asynchronous communication flow for processing of tasks. Unlike synchronous operations that require you to wait for a response while maintaining an active connection, asynchronous processing allows you to submit a request and check back later for results. The main advantage of this approach is that it is non-blocking, allowing you to perform other actions while the task is being processed.

Task

A task is a unit of work submitted for processing in Virtual Appliance. Each task is uniquely identified by a task_id within the system. A task carries information about its current state, any available results, and any errors that may have occurred during processing. Tasks exist in memory during the session and are cleaned up when Virtual Appliance restarts or shuts down.

Task state

A task progresses through a lifecycle of states as it is processed:

• Pending: The task is queued for processing but has not started yet.
• Running: The task is currently being processed.
• Done: The task has finished successfully and results are available.
• Failed: The task encountered an internal error during processing.
• Rejected: The task was rejected due to invalid input data detected during processing.
• Cancelled: The task was cancelled by the user and is being cleaned up.

A task reaches a terminal state when it is done, failed, or rejected. Finished tasks do not remain in memory indefinitely—they are automatically removed after a configurable expiration period.

Task creation

To create a task, submit a request to the task creation endpoint with the required parameters for your use case.

Successful creation

When a valid request is submitted:

• The system confirms the task has been accepted for processing.
• A unique task_id is returned to identify the task.
• The task is created internally with an initial pending state.
• The task is scheduled for processing (not processed immediately).

Failed creation

If the request is invalid or cannot be processed, the system returns an error and no task is created. Common reasons for failure include invalid or missing parameters, oversized requests, and insufficient system resources or licensing capacity.

Task polling

To check the state of a task or retrieve results after processing completes, query the system with the task_id. The system returns the current task state and any available results.

The task creation response includes a reference to the polling endpoint. You can poll the system at any time to check progress or retrieve results.

Task cancellation and deletion

Any task can be cancelled and deleted at any point in its lifecycle by submitting a cancellation request with the task_id.

Cancellation behavior:

• A task that has already finished (states done, rejected, or failed) is deleted immediately.
• A task that is still processing (states pending or running) is marked as cancelled and deleted as soon as possible.

You can cancel a task when the results are no longer needed or to free up processing and memory resources.

Task expiration

A task that has finished processing is automatically deleted after a configured expiration period. Once a task expires and is deleted, its results cannot be retrieved.

To avoid losing results, poll finished tasks regularly and retrieve their results before expiration. You can configure the expiration period based on your use case requirements.