Skip to main content
GET
/
v1
/
tasks
/
{task_id}
/
thread
Get Task'S Thread
curl --request GET \
  --url https://api.xpander.ai/v1/tasks/{task_id}/thread \
  --header 'x-api-key: <api-key>'
[
  {
    "role": "user",
    "content": "How do I reset my password?"
  },
  {
    "role": "assistant",
    "content": "To reset your password, visit the login page and click 'Forgot Password'. You'll receive a reset link via email."
  }
]
Retrieve the conversation thread for a task as a simple array. Returns only the root task’s messages (user requests and agent responses), excluding tool calls and internal routing.

​
Path Parameters

​
task_id
string
required
Unique identifier of the task (UUID format)

​
Response

Returns an array of message objects representing the conversation thread:
​
[array]
array
Array of conversation messages

​
Example Request

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

​
Example Response

Multi-turn conversation thread: 
[
  {
    "id": "<msg-id-1>",
    "role": "user",
    "content": "Hi, my name is David and I work at xpander.ai",
    "metrics": {
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0
    },
    "created_at": 1738945492
  },
  {
    "id": "<msg-id-2>",
    "role": "assistant",
    "content": "Hi David! Welcome. I'm here to help you with any questions or support needs. It's great to meet someone from the xpander.ai team!",
    "metrics": {
      "input_tokens": 247,
      "output_tokens": 2102,
      "total_tokens": 2349
    },
    "created_at": 1738945495
  },
  {
    "id": "<msg-id-3>",
    "role": "user",
    "content": "What is my name and where do I work?",
    "metrics": {
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0
    },
    "created_at": 1738945500
  },
  {
    "id": "<msg-id-4>",
    "role": "assistant",
    "content": "Your name is David and you work at xpander.ai.",
    "metrics": {
      "input_tokens": 165,
      "output_tokens": 2277,
      "total_tokens": 2442
    },
    "created_at": 1738945505
  }
]

​
Parsing Examples

Pretty print the conversation: 
curl -s -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>/thread" | \
  jq '.[] | "\(.role): \(.content)"'
Calculate total tokens used: 
curl -s -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>/thread" | \
  jq '[.[].metrics.total_tokens] | add'
Extract only assistant responses: 
curl -s -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>/thread" | \
  jq '.[] | select(.role == "assistant") | .content'

​
Use Cases

  • View conversation history - See the complete interaction between user and agent
  • Review agent responses - Understand what the agent said and its reasoning
  • Track token usage - Monitor LLM API costs per message
  • Audit conversations - Review interaction history for compliance

​
Notes

  • Returns only the root task’s messages (excludes sub-tasks)
  • For multi-agent workflows with sub-tasks, use Get Task Thread (Full)
  • Token metrics help you track and forecast LLM API costs
  • Messages are ordered chronologically by creation time

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
task_id
string
required

Response

Successful Response