> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Tasks by Agent Handle
> Retrieve all tasks assigned to a specific agent using its handle
```json Success Response (200) theme={null}
{
"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
}
]
}
```
```json Error Response (404) theme={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](/api/get-started/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/agent/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 ` |
| 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
```javascript Node.js theme={null}
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');
```
```python Python theme={null}
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')
```
```bash cURL theme={null}
# 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
1. **Agent Handle**: Use the exact agent handle from the [Get All Agents](/api/agent/get-all-agents) response
2. **Transcript Analysis**: Use the `transcript` field in the output for detailed conversation analysis
3. **Retry Logic**: Check `failure_count` and `last_failure_reason` for failed tasks to understand issues
4. **Recording Access**: Store `recording_url` from output for compliance and quality review
5. **Security**: Keep API tokens secure and rotate them regularly
## OpenAPI
````yaml GET /api/v2/platform/agents/{agent_handle}/tasks/
openapi: 3.0.3
info:
title: Unpod API
description: REST API for Unpod Voice AI Platform
version: 2.0.0
servers:
- url: https://unpod.ai/
description: QA
- url: https://unpod.ai/
description: Production
security: []
tags:
- name: Organisation
- name: Spaces
- name: Agents
- name: Tasks
- name: Runs
- name: Call Logs
- name: Analytics
- name: Providers
- name: Bridges
- name: Numbers
- name: Trunks
- name: Telephony
- name: Billing
paths:
/api/v2/platform/agents/{agent_handle}/tasks/:
get:
tags:
- Agents
summary: Get Tasks by Agent Handle
operationId: getTasksByAgentHandle
parameters:
- name: agent_handle
in: path
required: true
schema:
type: string
example: space-agent-8qmk42nslp91wrh3dz7btxc4
- $ref: '#/components/parameters/OrgHandle'
responses:
'200':
description: List of tasks for the agent
content:
application/json:
example:
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.
duration: 285
recording_url: >-
https://cdn.unpod.dev/recordings/CALL_7dAb3kR9mXvQ2pLw.mp3
transcript:
- role: agent
content: >-
Hello, this is an AI assistant. Am I speaking with
John Doe?
- role: user
content: Yes, this is John.
post_call_data:
summary: >-
Agent 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
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
security:
- TokenAuth: []
components:
parameters:
OrgHandle:
name: Org-Handle
in: header
required: true
schema:
type: string
example: unpod.tv
description: Organization domain handle
responses:
Unauthorized:
description: Unauthorized - Invalid or missing API token
content:
application/json:
example:
status_code: 401
message: Authentication credentials were not provided.
NotFound:
description: Resource not found
content:
application/json:
example:
status_code: 404
message: Not found.
securitySchemes:
TokenAuth:
type: apiKey
in: header
name: Authorization
description: 'Format: Token '
````