GET

api

platform

agents

{agent_handle}

tasks

Get Tasks by Agent Handle

curl --request GET \
  --url https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/ \
  --header 'Authorization: <api-key>' \
  --header 'Org-Handle: <org-handle>'

import requests

url = "https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/"

headers = {
    "Org-Handle": "<org-handle>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Org-Handle': '<org-handle>', Authorization: '<api-key>'}
};

fetch('https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/', 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://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Org-Handle: <org-handle>"
  ],
]);

$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://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/"

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

	req.Header.Add("Org-Handle", "<org-handle>")
	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/")
  .header("Org-Handle", "<org-handle>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/")

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

request = Net::HTTP::Get.new(url)
request["Org-Handle"] = '<org-handle>'
request["Authorization"] = '<api-key>'

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

{
  "count": 1,
  "status_code": 200,
  "message": "Tasks Fetched Successfully",
  "data": [
    {
      "_id": "697debb84c27faa892bfa0cc",
      "thread_id": "thread_9xkL2mQpR7vNwY4sZ3cJ8hF1",
      "user_info": {
        "email": "user@example.com",
        "full_name": "John Doe"
      },
      "task_id": "T8ff2ccdffe9a11f0878d43cd8a99e069",
      "run_id": "R8ff2ccdefe9a11f0878d43cd8a99e069",
      "task": {
        "objective": "Call the lead and discuss the project requirements."
      },
      "input": {
        "name": "John Doe",
        "contact_number": "1234567890",
        "email": "john@example.com",
        "context": "Follow up on proposal"
      },
      "output": {
        "call_id": "CALL_7dAb3kR9mXvQ2pLw",
        "call_end_reason": "caller_hangup",
        "start_time": "2026-02-07T05:57:45Z",
        "end_time": "2026-02-07T06:02:30Z",
        "assistant_number": "+911234567890",
        "call_summary": "The agent successfully connected with John Doe and discussed project requirements. Lead expressed interest.",
        "duration": 285,
        "recording_url": "https://cdn.unpod.ai/recordings/CALL_7dAb3kR9mXvQ2pLw.mp3",
        "transcript": [
          {
            "role": "agent",
            "content": "Hello, this is an AI assistant calling on behalf of Unpod. Am I speaking with John Doe?"
          },
          {
            "role": "user",
            "content": "Yes, this is John."
          }
        ],
        "post_call_data": {
          "summary": "The agent successfully connected with John Doe and discussed project requirements.",
          "outcome": "interested",
          "sentiment": "positive"
        },
        "call_type": "outbound",
        "call_status": "completed"
      },
      "attachments": [],
      "assignee": "space-agent-8qmk42nslp91wrh3dz7btxc4",
      "status": "completed",
      "execution_type": "call",
      "ref_id": "6902fb5840a736e125e80ebc",
      "failure_count": 0,
      "last_failure_reason": null,
      "retry_attempt": 0,
      "last_status_change": "2026-02-07T06:02:35Z",
      "scheduled_timestamp": null
    }
  ]
}

{
  "message": "Agent not found"
}

{
  "count": 1,
  "status_code": 200,
  "message": "Tasks Fetched Successfully",
  "data": [
    {
      "_id": "697debb84c27faa892bfa0cc",
      "thread_id": "thread_9xkL2mQpR7vNwY4sZ3cJ8hF1",
      "user_info": {
        "email": "user@example.com",
        "full_name": "John Doe"
      },
      "task_id": "T8ff2ccdffe9a11f0878d43cd8a99e069",
      "run_id": "R8ff2ccdefe9a11f0878d43cd8a99e069",
      "task": {
        "objective": "Call the lead and discuss the project requirements."
      },
      "input": {
        "name": "John Doe",
        "contact_number": "1234567890",
        "email": "john@example.com",
        "context": "Follow up on proposal"
      },
      "output": {
        "call_id": "CALL_7dAb3kR9mXvQ2pLw",
        "call_end_reason": "caller_hangup",
        "start_time": "2026-02-07T05:57:45Z",
        "end_time": "2026-02-07T06:02:30Z",
        "assistant_number": "+911234567890",
        "call_summary": "The agent successfully connected with John Doe and discussed project requirements. Lead expressed interest.",
        "duration": 285,
        "recording_url": "https://cdn.unpod.ai/recordings/CALL_7dAb3kR9mXvQ2pLw.mp3",
        "transcript": [
          {
            "role": "agent",
            "content": "Hello, this is an AI assistant calling on behalf of Unpod. Am I speaking with John Doe?"
          },
          {
            "role": "user",
            "content": "Yes, this is John."
          }
        ],
        "post_call_data": {
          "summary": "The agent successfully connected with John Doe and discussed project requirements.",
          "outcome": "interested",
          "sentiment": "positive"
        },
        "call_type": "outbound",
        "call_status": "completed"
      },
      "attachments": [],
      "assignee": "space-agent-8qmk42nslp91wrh3dz7btxc4",
      "status": "completed",
      "execution_type": "call",
      "ref_id": "6902fb5840a736e125e80ebc",
      "failure_count": 0,
      "last_failure_reason": null,
      "retry_attempt": 0,
      "last_status_change": "2026-02-07T06:02:35Z",
      "scheduled_timestamp": null
    }
  ]
}

{
  "message": "Agent not found"
}

Get Tasks by Agent Handle

Fetch all tasks assigned to a specific agent/pilot using their handle. This returns full task metadata including user info, input payloads, call output, transcripts, and execution details.

Prerequisites: Make sure you have your API Token ready. See Authentication for details.

Path Parameters

Name	Type	Required	Description
agent_handle	string	Yes	Unique handle/identifier of the agent

You can get the agent_handle by hitting the Get All Agents API. The handle field in the response is your Agent Handle.

Headers

Name	Type	Required	Description
Authorization	string	Yes	API Key format: `Token <token>`
Content-Type	string	Yes	`application/json`

Response Fields

Field	Type	Description
count	integer	Total number of tasks
status_code	integer	HTTP status code
message	string	Response message
data	array	Array of task objects

Task Object Fields

Field	Type	Description
_id	string	Internal task document ID
thread_id	string	Thread identifier
user_info	object	User details (email, full_name)
task_id	string	Unique task identifier
run_id	string	Parent run identifier
task	object	Task definition with objective
input	object	Input data for the task
output	object	Task output with call details
attachments	array	List of attachments
assignee	string	Agent handle assigned to the task
status	string	Task status: `pending`, `completed`, `failed`
execution_type	string	Type of execution: `call`, `email`, etc.
ref_id	string	Reference ID linking to input data
failure_count	integer	Number of failed attempts
last_failure_reason	string	Reason for last failure (null if none)
retry_attempt	integer	Current retry attempt number
last_status_change	string	Timestamp of last status change
scheduled_timestamp	string	Scheduled execution timestamp (null if now)

Output Object Fields

Field	Type	Description
call_id	string	Unique call identifier
call_end_reason	string	Reason for call ending
start_time	string	Call start timestamp
end_time	string	Call end timestamp
assistant_number	string	Outbound phone number used
call_summary	string	AI-generated summary of the call
duration	number	Call duration in seconds
recording_url	string	URL to call recording
transcript	array	Array of conversation messages
post_call_data	object	Post-call analysis data
call_type	string	Direction of call: `outbound`, `inbound`
call_status	string	Status of the call: `completed`, etc.

Common Error Codes

Status Code	Description
200	Success - Data fetched successfully
206	Partial Content - Business logic error occurred
400	Bad Request - Invalid parameters provided
401	Unauthorized - Invalid or missing API token
403	Forbidden - Access denied to the resource
404	Not Found - Agent not found
500	Internal Server Error - Server-side error

Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Content-Type': 'application/json'
};

// Get tasks by agent handle
const getTasksByAgentHandle = async (agentHandle) => {
  const response = await axios.get(
    `https://unpod.ai/api/v2/platform/agents/${agentHandle}/tasks/`,
    { headers }
  );
  console.log(`Total tasks: ${response.data.count}`);
  response.data.data.forEach(task => {
    console.log(`Task ${task.task_id}: ${task.status} (${task.execution_type})`);
  });
  return response.data.data;
};

// Example usage
getTasksByAgentHandle('space-agent-8qmk42nslp91wrh3dz7btxc4');

import requests

headers = {
    'Authorization': 'Token your-api-token',
    'Content-Type': 'application/json'
}

def get_tasks_by_agent_handle(agent_handle: str):
    """Get all tasks assigned to a specific agent"""
    url = f'https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/'
    response = requests.get(url, headers=headers)
    data = response.json()
    print(f"Total tasks: {data['count']}")
    for task in data['data']:
        print(f"Task {task['task_id']}: {task['status']} ({task['execution_type']})")
    return data['data']

# Example usage
get_tasks_by_agent_handle('space-agent-8qmk42nslp91wrh3dz7btxc4')

# Get tasks by agent handle
curl -X GET "https://unpod.ai/api/v2/platform/agents/space-agent-8qmk42nslp91wrh3dz7btxc4/tasks/" \
  -H "Authorization: Token your-api-token" \
  -H "Content-Type: application/json"

Best Practices

Agent Handle: Use the exact agent handle from the Get All Agents response
Transcript Analysis: Use the transcript field in the output for detailed conversation analysis
Retry Logic: Check failure_count and last_failure_reason for failed tasks to understand issues
Recording Access: Store recording_url from output for compliance and quality review
Security: Keep API tokens secure and rotate them regularly

Authorizations

Authorization

string

header

required

Format: Token

Headers

Org-Handle

string

required

Organization domain handle

Example:

"unpod.tv"

Path Parameters

agent_handle

string

required

Example:

"space-agent-8qmk42nslp91wrh3dz7btxc4"

Response

List of tasks for the agent

Get All Agent ExecutionsRetrieve all executions (call runs) for a specific agent

Get Tasks by Agent Handle

curl --request GET \
  --url https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/ \
  --header 'Authorization: <api-key>' \
  --header 'Org-Handle: <org-handle>'

import requests

url = "https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/"

headers = {
    "Org-Handle": "<org-handle>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Org-Handle': '<org-handle>', Authorization: '<api-key>'}
};

fetch('https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/', 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://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Org-Handle: <org-handle>"
  ],
]);

$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://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/"

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

	req.Header.Add("Org-Handle", "<org-handle>")
	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/")
  .header("Org-Handle", "<org-handle>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://unpod.ai/api/v2/platform/agents/{agent_handle}/tasks/")

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

request = Net::HTTP::Get.new(url)
request["Org-Handle"] = '<org-handle>'
request["Authorization"] = '<api-key>'

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

{
  "count": 1,
  "status_code": 200,
  "message": "Tasks Fetched Successfully",
  "data": [
    {
      "_id": "697debb84c27faa892bfa0cc",
      "thread_id": "thread_9xkL2mQpR7vNwY4sZ3cJ8hF1",
      "user_info": {
        "email": "user@example.com",
        "full_name": "John Doe"
      },
      "task_id": "T8ff2ccdffe9a11f0878d43cd8a99e069",
      "run_id": "R8ff2ccdefe9a11f0878d43cd8a99e069",
      "task": {
        "objective": "Call the lead and discuss the project requirements."
      },
      "input": {
        "name": "John Doe",
        "contact_number": "1234567890",
        "email": "john@example.com",
        "context": "Follow up on proposal"
      },
      "output": {
        "call_id": "CALL_7dAb3kR9mXvQ2pLw",
        "call_end_reason": "caller_hangup",
        "start_time": "2026-02-07T05:57:45Z",
        "end_time": "2026-02-07T06:02:30Z",
        "assistant_number": "+911234567890",
        "call_summary": "The agent successfully connected with John Doe and discussed project requirements. Lead expressed interest.",
        "duration": 285,
        "recording_url": "https://cdn.unpod.ai/recordings/CALL_7dAb3kR9mXvQ2pLw.mp3",
        "transcript": [
          {
            "role": "agent",
            "content": "Hello, this is an AI assistant calling on behalf of Unpod. Am I speaking with John Doe?"
          },
          {
            "role": "user",
            "content": "Yes, this is John."
          }
        ],
        "post_call_data": {
          "summary": "The agent successfully connected with John Doe and discussed project requirements.",
          "outcome": "interested",
          "sentiment": "positive"
        },
        "call_type": "outbound",
        "call_status": "completed"
      },
      "attachments": [],
      "assignee": "space-agent-8qmk42nslp91wrh3dz7btxc4",
      "status": "completed",
      "execution_type": "call",
      "ref_id": "6902fb5840a736e125e80ebc",
      "failure_count": 0,
      "last_failure_reason": null,
      "retry_attempt": 0,
      "last_status_change": "2026-02-07T06:02:35Z",
      "scheduled_timestamp": null
    }
  ]
}

{
  "message": "Agent not found"
}

Getting Started

API Lists

Get Tasks by Agent Handle

Get Tasks by Agent Handle

Path Parameters

Headers

Response Fields

Task Object Fields

Output Object Fields

Common Error Codes

Code Examples

Best Practices

Authorizations

Headers

Path Parameters

Response

​Get Tasks by Agent Handle

​Path Parameters

​Headers

​Response Fields

​Task Object Fields

​Output Object Fields

​Common Error Codes

​Code Examples

​Best Practices

Authorizations

Headers

Path Parameters

Response

Get Tasks by Agent Handle

Path Parameters

Headers

Response Fields

Task Object Fields

Output Object Fields

Common Error Codes

Code Examples

Best Practices