> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gym.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Status

> Check the status of a background task

Retrieves the current status and results of a background task started by endpoints like `/create_desktop` or `/reset`.

## Path Parameters

<ParamField path="task_id" type="string" required>
  Task identifier returned by the original request
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Task identifier
</ResponseField>

<ResponseField name="task_type" type="string">
  Type of task (`create_desktop`, `reset_environment`)
</ResponseField>

<ResponseField name="status" type="string">
  Current status (`running`, `completed`, `failed`)
</ResponseField>

<ResponseField name="start_time" type="number">
  Unix timestamp when task started
</ResponseField>

<ResponseField name="duration" type="number">
  Elapsed time in seconds (if running)
</ResponseField>

<ResponseField name="end_time" type="number">
  Unix timestamp when task ended (if completed/failed)
</ResponseField>

<ResponseField name="total_duration" type="number">
  Total execution time in seconds (if completed/failed)
</ResponseField>

<ResponseField name="result" type="object">
  Task result (if completed)
</ResponseField>

<ResponseField name="error" type="string">
  Error message (if failed)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "http://CONTROL_PLANE_IP:PORT/task_status/uuid-string"
  ```
</RequestExample>

<ResponseExample>
  ```json Running theme={null}
  {
    "task_id": "uuid-string",
    "task_type": "create_desktop",
    "status": "running",
    "start_time": 1234567890.123,
    "duration": 5.333
  }
  ```

  ```json Completed theme={null}
  {
    "task_id": "uuid-string",
    "task_type": "create_desktop",
    "status": "completed",
    "start_time": 1234567890.123,
    "end_time": 1234567895.456,
    "total_duration": 5.333,
    "result": {
      "status": "success",
      "message": "Desktop environment created successfully",
      "vm_id": "vm-abc123",
      "vnc_url": "https://...",
      "vnc_port": 8000
    }
  }
  ```

  ```json Failed theme={null}
  {
    "task_id": "uuid-string",
    "task_type": "create_desktop",
    "status": "failed",
    "start_time": 1234567890.123,
    "end_time": 1234567892.456,
    "total_duration": 2.333,
    "error": "Failed to create VM: resource limit exceeded"
  }
  ```
</ResponseExample>