Get Task

Get Task

curl --request GET \
  --url https://api.xpander.ai/v1/tasks/{task_id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/tasks/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "f0f0f0f0-1111-2222-3333-444444444444",
  "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
  "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
  "status": "completed",
  "input": {
    "text": "Summarize today's signups.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  },
  "result": "42 new signups today, up 12% week over week.",
  "created_at": "2026-07-28T20:59:02.915959Z",
  "finished_at": "2026-07-28T20:59:51.661537Z",
  "llm_model_provider": "anthropic",
  "llm_model_name": "claude-sonnet-5",
  "tokens": {
    "input_tokens": 70216,
    "output_tokens": 3496,
    "total_tokens": 73712
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

GET

tasks

{task_id}

Get Task

curl --request GET \
  --url https://api.xpander.ai/v1/tasks/{task_id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/tasks/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "f0f0f0f0-1111-2222-3333-444444444444",
  "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
  "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
  "status": "completed",
  "input": {
    "text": "Summarize today's signups.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  },
  "result": "42 new signups today, up 12% week over week.",
  "created_at": "2026-07-28T20:59:02.915959Z",
  "finished_at": "2026-07-28T20:59:51.661537Z",
  "llm_model_provider": "anthropic",
  "llm_model_name": "claude-sonnet-5",
  "tokens": {
    "input_tokens": 70216,
    "output_tokens": 3496,
    "total_tokens": 73712
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Get complete details about a task/thread record including its current status, latest input, latest result, and execution timing. This endpoint is essential for polling async tasks and for inspecting the latest turn of a continued conversation.

Path Parameters

string

required

Unique identifier of the task to retrieve (UUID format)

Response

string

Task/thread identifier. Reuse this as id in later invokes to continue the same conversation.

string

UUID of the agent that executed this task

string

UUID of the organization that owns this task

object

Latest input stored on this task/thread record

Show Input Object

string

Text message or query

array

Array of file references (if any)

object

User information (nullable)

string

Current task status: pending, executing, paused, error, failed, completed, or stopped

string

Latest task result. This is usually plain text or markdown. Only parse it as JSON if you explicitly requested JSON/structured output.

string

Output format for the latest result, such as markdown or json

string

ISO 8601 timestamp of when the task was created

string

ISO 8601 timestamp of when execution began (null if not started)

string

ISO 8601 timestamp of when the task finished (null if still running)

string

Source of the task creation: api, sdk, dashboard, webhook

boolean

Whether the task used event streaming

array

Array of sub-task UUIDs spawned by this task

string

UUID of parent task if this is a sub-task (null otherwise)

object

Additional metadata (nullable)

In a multi-turn conversation, this endpoint shows the latest input and latest result for the reused task/thread ID. Use Get Task Thread or Get Task Thread (Full) for the full message history.

Example Request

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>"

Example Response

{
  "id": "fbd08e4d-cfa7-4838-b6e6-e51855ac2ba3",
  "agent_id": "<agent-id>",
  "organization_id": "<org-id>",
  "input": {
    "text": "Reply with exactly SECOND",
    "files": [],
    "user": null
  },
  "status": "completed",
  "created_at": "2026-03-23T00:45:26.965823Z",
  "started_at": null,
  "finished_at": "2026-03-23T00:45:30.532954Z",
  "result": "SECOND",
  "source": "api",
  "output_format": "markdown",
  "events_streaming": true,
  "sub_executions": [],
  "parent_execution": null,
  "payload_extension": null
}

Extracting Results

For normal text or markdown responses:

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>" | jq -r '.result'

Only use fromjson when you explicitly requested JSON output:

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>" | jq '.result | fromjson'

Status Polling Pattern

For async workflows, poll until status is no longer pending or executing:

# Poll every 2 seconds until task completes
while true; do
  TASK=$(curl -s -H "x-api-key: <your-api-key>" \
    "https://api.xpander.ai/v1/tasks/<task-id>")

  STATUS=$(echo $TASK | jq -r '.status')

  if [[ $STATUS == "completed" ]]; then
    echo $TASK | jq -r '.result'
    break
  fi

  sleep 2
done

Use Cases

Retrieve task results - Get final output after async execution
Check execution status - Monitor if task is still executing
Track timing - See created_at, started_at, finished_at for performance analysis
Get latest-turn details - Review the most recent input and output for a continued conversation

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

task_id

string

required

Response

Successful Response

string

required

agent_id

string

required

organization_id

string

required

input

AgentExecutionInput · object

required

Show child attributes

created_at

string<date-time>

required

status

enum<string> | null

default:pending

Available options:

pending,

executing,

paused,

error,

failed,

completed,

stopped

internal_status

string | null

last_executed_node_id

string | null

agent_version

string | null

started_at

string<date-time> | null

paused_at

string<date-time> | null

finished_at

string<date-time> | null

result

string | null

parent_execution

string | null

sub_executions

string[] | null

finished_sub_executions

string[] | null

should_update_parent

boolean | null

default:false

is_manually_stopped

boolean | null

default:false

is_background

boolean | null

default:false

payload_extension

Payload Extension · object | null

hitl_request

HumanInTheLoopRequest · object | null

Model representing human-in-the-loop approval records for tasks.

Attributes: wait_node_id (str): The id of the node that triggered this HITL.

Show child attributes

pending_eca_request

PendingECARequest · object | null

Show child attributes

source

string | null

worker_id

string | null

additional_context

string | null

instructions_override

string | null

expected_output

string | null

test_run_node_id

string | null

is_orchestration

boolean | null

default:false

is_gateway

boolean | null

default:false

is_app

boolean | null

default:false

sub_tasks_mode

enum<string> | null

Available options:

sync,

async,

auto

output_format

enum<string> | null

default:text

Available options:

text,

markdown,

json,

voice

voice_id

string | null

output_schema

Output Schema · object | null

events_streaming

boolean | null

default:false

used_mutating_tools

boolean | null

default:false

is_continuous

boolean | null

default:false

mcp_servers

Mcp Servers · object[] | null

triggering_agent_id

string | null

title

string | null

think_mode

enum<string> | null

default:default

Available options:

default,

harder

disable_attachment_injection

boolean | null

default:false

deep_planning

DeepPlanning · object | null

Show child attributes

must_deep_plan

boolean | null

default:false

execution_attempts

integer | null

default:1

user_tokens

User Tokens · object | null

user_oidc_token

string | null

return_metrics

boolean | null

default:false

tokens

LLMTokens · object | null

Show child attributes

llm_model_provider

string | null

Snapshot of the LLM provider used for this execution (request override or agent default at run time).

llm_model_name

string | null

Snapshot of the LLM model name used for this execution (request override or agent default at run time).

llm_reasoning_effort

enum<string> | null

Snapshot of the reasoning effort applied during this execution, when supported by the model.

Available options:

low,

medium,

high,

xhigh

List Tasks

Stop Task

⌘I

Overview

REST API - Agents

REST API - Scheduled Tasks

REST API - Self-Schedules

Agent Workspace

REST API - Agent Gateway

REST API - Tasks

REST API - Knowledge

REST API - Workflows

REST API - Tools

REST API - Custom Functions

REST API - Misc

Path Parameters

Response

Example Request

Example Response

Extracting Results

Status Polling Pattern

Use Cases

Authorizations

Path Parameters

Response

​Path Parameters

​Response

​Example Request

​Example Response

​Extracting Results

​Status Polling Pattern

​Use Cases

Authorizations

Path Parameters

Response

Path Parameters

Response

Example Request

Example Response

Extracting Results

Status Polling Pattern

Use Cases