Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mulerouter.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

All MuleRouter asynchronous tasks follow the same usage pattern: Create a task via a POST request, then use GET requests to retrieve its latest status and result.

​
Task response structure

All asynchronous task responses follow the structure below:

​
Task Information Object

​
task_info
object
required
Task Information object

​
Task Result

The corresponding JSON structure is as follows: 
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "queued",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:00:00Z"
  }
}
When querying, use the task ID to fetch the execution status and result.

​
Create a task

MuleRouter integrates multiple model vendors. Some requests are synchronous or streaming, while others involve longer inference cycles. To improve the developer experience, we expose these as asynchronous tasks. Create an asynchronous task via POST /vendors/dummy/v1/videos/generation. You will receive a response similar to the following: 
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "queued",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:00:00Z"
  },
  ...
}

​
Retrieve task status and result

In the above example, the task ID is 123e4567-e89b-12d3-a456-426614174000. To retrieve the latest status and result for the task ID. Use GET /vendors/dummy/v1/videos/generation/123e4567-e89b-12d3-a456-426614174000. For example, when the task status is succeeded, you may receive a response like the following: 
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "succeeded",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:00:00Z"
  },
  "videos": [
    "https://example.com/video-749337402830284.mp4"
  ]
}
The exact result payload varies by endpoint, refer to the model documentation. The task info response envelope remains consistent.

​
Failed tasks

If a task finishes with status: "failed", the response includes an error object describing what went wrong. The HTTP status of the GET itself is still 200 — the lookup succeeded, the task it describes did not. 
{
  "task_info": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "failed",
    "created_at": "2025-09-16T10:00:00Z",
    "updated_at": "2025-09-16T10:02:13Z"
  },
  "error": {
    "title": "External service execution failed",
    "error_code": 3005,
    "detail": "Kling task failed: video generation failed due to prompt violation"
  }
}
The error_code is the authoritative signal for what went wrong. The most common codes for failed async tasks are:
  • 3001 – 3005: the upstream model provider could not complete the task.
  • 4002, 4008: a MuleRouter-side error occurred while running the task.
See Error Codes for the full list and the meaning of each code.

​
Task lifecycle

StatusMeaning
queuedTask accepted and waiting to be picked up by a worker.
runningA worker has claimed the task and is executing it.
succeededTask finished successfully. The result payload (endpoint-specific) is present.
failedTask ended with an error. An error object is present.
A task only ever leaves queued / running once — once it is succeeded or failed, it stays in that state.

​
Common errors

SituationWhere it surfacesCode
POST body fails validationPOST returns 400 synchronously2001–2004
Required file too large or wrong formatPOST returns 400 synchronously2101–2103
task_id in GET does not existGET returns 404 synchronously2005
Caller has no balance / over quotaPOST returns 402 / 429 synchronously1003–1005
Upstream provider could not complete the taskGET returns 200 with status: failed3001–3005
Server-side error while running the taskGET returns 200 with status: failed4002, 4008