# Retrieve batch task status

> Common

Retrieve batch task details and status by batch ID. When `status`
becomes `completed`, use `output_file_id` (successful results) and
`error_file_id` (failure details, if any) from the response to download
the results.

## Endpoint

`GET https://api.modelverse.cn/v1/batches/{batch_id}`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| batch_id | path | string | Yes | Batch task ID returned by the create endpoint. |

## Responses

- **200** — Batch task details.
- **404** — Task not found or not accessible.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Batch Tasks - Retrieve Batch Status",
    "version": "1.0.0",
    "description": "Step 4 of the ModelVerse **OpenAI-compatible Batch async task** flow:\npoll the batch task status. After creating a task, poll its status until it\nreaches a terminal state (`completed` / `failed` / `expired` / `cancelled`).\nEndpoint: `GET /v1/batches/{batch_id}`. A polling interval of at least 30s\nis recommended.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "Batch Async Tasks",
      "description": "OpenAI-compatible batch async task APIs."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/batches/{batch_id}": {
      "get": {
        "tags": [
          "Batch Async Tasks"
        ],
        "operationId": "retrieveBatch",
        "summary": "Retrieve batch task status",
        "description": "Retrieve batch task details and status by batch ID. When `status`\nbecomes `completed`, use `output_file_id` (successful results) and\n`error_file_id` (failure details, if any) from the response to download\nthe results.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "batch_id",
            "in": "path",
            "required": true,
            "description": "Batch task ID returned by the create endpoint.",
            "schema": {
              "type": "string"
            },
            "example": "batch_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "Batch task details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchObject"
                },
                "examples": {
                  "completed": {
                    "summary": "Task completed",
                    "value": {
                      "id": "batch_abc123",
                      "object": "batch",
                      "endpoint": "/v1/chat/completions",
                      "errors": null,
                      "input_file_id": "file-abc123",
                      "completion_window": "24h",
                      "status": "completed",
                      "output_file_id": "file-out456",
                      "error_file_id": "",
                      "created_at": 1781600010,
                      "in_progress_at": 1781600030,
                      "finalizing_at": 1781600300,
                      "completed_at": 1781600360,
                      "request_counts": {
                        "total": 2,
                        "completed": 2,
                        "failed": 0
                      }
                    }
                  },
                  "inProgress": {
                    "summary": "Task in progress",
                    "value": {
                      "id": "batch_abc123",
                      "object": "batch",
                      "endpoint": "/v1/chat/completions",
                      "errors": null,
                      "input_file_id": "file-abc123",
                      "completion_window": "24h",
                      "status": "in_progress",
                      "created_at": 1781600010,
                      "in_progress_at": 1781600030,
                      "request_counts": {
                        "total": 2,
                        "completed": 1,
                        "failed": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Task not found or not accessible.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/BatchError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/BatchError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Provide the API key via the `Authorization` header as\n`Bearer <your_api_key>`.\n"
      }
    },
    "schemas": {
      "BatchObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "object",
          "endpoint",
          "input_file_id",
          "completion_window",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Batch task ID."
          },
          "object": {
            "type": "string",
            "const": "batch",
            "description": "Object type. Always `batch`."
          },
          "endpoint": {
            "type": "string",
            "description": "Target endpoint that processes requests."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Error object; `null` when there are no errors."
          },
          "input_file_id": {
            "type": "string",
            "description": "Input file ID."
          },
          "completion_window": {
            "type": "string",
            "description": "Task completion window."
          },
          "status": {
            "type": "string",
            "description": "Task status: `validating` (validating input file),\n`in_progress` (running), `finalizing` (preparing results),\n`completed`, `failed`, `expired`, `cancelling`, `cancelled`.\n",
            "enum": [
              "validating",
              "in_progress",
              "finalizing",
              "completed",
              "failed",
              "expired",
              "cancelling",
              "cancelled"
            ]
          },
          "output_file_id": {
            "type": "string",
            "description": "Result file ID; used to download successful results after completion."
          },
          "error_file_id": {
            "type": "string",
            "description": "Error detail file ID; used to download failure details."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp (seconds)."
          },
          "in_progress_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Timestamp when execution started (seconds)."
          },
          "finalizing_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Timestamp when result preparation started (seconds)."
          },
          "completed_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Completion timestamp (seconds)."
          },
          "failed_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Failure timestamp (seconds)."
          },
          "expired_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Expiration timestamp (seconds)."
          },
          "cancelled_at": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Cancellation-completed timestamp (seconds)."
          },
          "request_counts": {
            "$ref": "#/components/schemas/BatchRequestCounts"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Custom metadata provided at creation."
          }
        }
      },
      "BatchRequestCounts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of requests."
          },
          "completed": {
            "type": "integer",
            "description": "Number of completed requests."
          },
          "failed": {
            "type": "integer",
            "description": "Number of failed requests."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code."
          },
          "param": {
            "type": "string",
            "description": "The offending parameter name or request ID."
          }
        }
      }
    },
    "examples": {
      "BatchError": {
        "summary": "Standard JSON error response",
        "value": {
          "error": {
            "message": "batch not found",
            "type": "invalid_request_error",
            "code": "not_found",
            "param": "batch_id"
          }
        }
      }
    }
  }
}
```