MuleRouter Documentation - AI API Gateway & Routing Platform

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

Hide properties

task_info.id

string

required

Task ID, UUID format

task_info.status

string

required

Task Status. Enum: queued, running, succeeded, failed

task_info.created_at

string

required

Task Created Timestamp, ISO 8601 format

task_info.updated_at

string

required

Task Updated Timestamp, ISO 8601 format

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

Status	Meaning
`queued`	Task accepted and waiting to be picked up by a worker.
`running`	A worker has claimed the task and is executing it.
`succeeded`	Task finished successfully. The result payload (endpoint-specific) is present.
`failed`	Task 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

Situation	Where it surfaces	Code
`POST` body fails validation	`POST` returns `400` synchronously	`2001`–`2004`
Required file too large or wrong format	`POST` returns `400` synchronously	`2101`–`2103`
`task_id` in `GET` does not exist	`GET` returns `404` synchronously	`2005`
Caller has no balance / over quota	`POST` returns `402` / `429` synchronously	`1003`–`1005`
Upstream provider could not complete the task	`GET` returns `200` with `status: failed`	`3001`–`3005`
Server-side error while running the task	`GET` returns `200` with `status: failed`	`4002`, `4008`

Overview

Core concepts

Asynchronous Tasks

Task response structure

Task Information Object

Task Result

Create a task

Retrieve task status and result

Failed tasks

Task lifecycle

Common errors

​Task response structure

​Task Information Object

​Task Result

​Create a task

​Retrieve task status and result

​Failed tasks

​Task lifecycle

​Common errors

Task response structure

Task Information Object

Task Result

Create a task

Retrieve task status and result

Failed tasks

Task lifecycle

Common errors