/tasks/{id}

GET SYNC

Returns information about a previously created task from an asynchronous call.

GET /api/v1/tasks/{id}

Alias: /get-task-status/{id}

Description

This endpoint retrieves the current status and progress of a background task. Asynchronous operations like /backup or /join immediately return a task object with a unique ID. You should then periodically call this endpoint with that ID to monitor the task until it is `completed` or has an `error`.

Polling this Endpoint

This is a synchronous call that returns the current state of an asynchronous task. It is designed to be polled at regular intervals (e.g., every 2-3 seconds) to provide feedback to the user.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The 32-character GUID of the task, returned by the initial asynchronous API call.

Response

Returns a `200 OK` response with a task object detailing the current state of the background job.

Response Properties

statusstring

The overall status of the API call itself, which should be "success".

payloadobject

The object containing the detailed task information.

Payload Object Properties

idstring

The unique identifier (GUID) for the task.

statusstring

The current status of the task: "running", "completed", or "error".

progressinteger

The progress of the task as a percentage (0-100).

messagestring

A user-friendly status message or error detail.

dataobject | string

The result data for the completed task. This field is only present when the task `status` is "completed". Its structure depends on the original API call.

Example Response (Task in Progress)

{
    "status": "success",
    "payload": {
        "id": "bdc8e99d-dd8a-40e9-8840-f9f8eef16c71",
        "status": "running",
        "progress": 50,
        "message": "Processing...",
        "data": null
    }
}

Example Response (Task Completed)

{
    "status": "success",
    "payload": {
        "id": "bdc8e99d-dd8a-40e9-8840-f9f8eef16c71",
        "status": "completed",
        "progress": 100,
        "message": "Command Completed",
        "data": {
            "online": 25,
            "pownstring": "ppppppppppppppppppppppppp",
            "pownarray": [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
            "latencies": [1104,1417,1407,1397,1416,1405,1412,1397,1407,1406]
        }
    }
}

Examples

JavaScript Example

const apiHost = 'http://localhost:8006';

// This function would be called repeatedly until the task is no longer "running"
async function pollTask(taskId) {
    try {
        const response = await fetch(`${apiHost}/api/v1/tasks/${taskId}`);
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        const taskData = await response.json();
        const task = taskData.payload;

        console.log(`Task ${taskId} progress: ${task.progress}% - ${task.message}`);

        if (task.status === 'completed') {
            console.log('Task finished successfully!', task.data);
            // Stop polling and handle the final data
            return true;
        } else if (task.status === 'error') {
            console.error('Task failed:', task.message);
            // Stop polling and handle the error
            return true;
        }
        // Task is still running, continue polling
        return false;
    } catch (error) {
        console.error('Error polling task status:', error);
        return true; // Stop polling on error
    }
}

// Example of how to use the poller
const taskId = 'bdc8e99d-dd8a-40e9-8840-f9f8eef16c71'; // ID from an async call
const pollInterval = setInterval(async () => {
    const isDone = await pollTask(taskId);
    if (isDone) {
        clearInterval(pollInterval);
    }
}, 2000); // Check every 2 seconds

cURL Example

# This script polls a task ID until it completes or fails.
# Replace the TASK_ID with the one you received from an async call.

TASK_ID="bdc8e99d-dd8a-40e9-8840-f9f8eef16c71"

echo "Polling task with ID: $TASK_ID"

while true; do
  RESPONSE=$(curl -s "http://localhost:8006/api/v1/tasks/$TASK_ID")
  STATUS=$(echo $RESPONSE | jq -r '.payload.status')
  PROGRESS=$(echo $RESPONSE | jq -r '.payload.progress')
  
  echo "Polling... Status: $STATUS, Progress: $PROGRESS%"
  
  if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "error" ]]; then
    echo "Final Response:"
    echo $RESPONSE | jq
    break
  fi
  
  sleep 2
done

Go Example

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "time"
)

const apiHost = "http://localhost:8006/api/v1"

type TaskResponse struct {
    Payload struct {
        ID       string      `json:"id"`
        Status   string      `json:"status"`
        Progress int         `json:"progress"`
        Message  string      `json:"message"`
        Data     interface{} `json:"data"`
    } `json:"payload"`
}

// pollTask polls a task until it is complete or fails.
func pollTask(taskId string) {
    for {
        resp, err := http.Get(fmt.Sprintf("%s/tasks/%s", apiHost, taskId))
        if err != nil {
            log.Printf("Error polling task: %v\n", err)
            return
        }
        defer resp.Body.Close()

        var taskResp TaskResponse
        if err := json.NewDecoder(resp.Body).Decode(&taskResp); err != nil {
            log.Printf("Error decoding task response: %v\n", err)
            time.Sleep(2 * time.Second)
            continue
        }

        fmt.Printf("Polling... Status: %s, Progress: %d%%\n", taskResp.Payload.Status, taskResp.Payload.Progress)

        if taskResp.Payload.Status == "completed" {
            fmt.Printf("Task completed successfully. Result: %+v\n", taskResp.Payload.Data)
            return
        } else if taskResp.Payload.Status == "error" {
            fmt.Printf("Task failed: %s\n", taskResp.Payload.Message)
            return
        }
        time.Sleep(2 * time.Second)
    }
}

func main() {
    // Assume this ID was returned from a previous async call like /backup or /join
    taskId := "bdc8e99d-dd8a-40e9-8840-f9f8eef16c71"
    pollTask(taskId)
}