Tasks API

The Tasks API allows you to manage and retrieve tasks in your Unpod platform. Tasks represent individual execution units within a run or space.

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

Create a Task in a Space

Create a new task inside a given space using the space’s public token. You can assign the task to a pilot/agent, attach multiple documents, provide additional context, and optionally schedule the execution.

POST /api/v2/platform/spaces/{space_token}/tasks/

Path Parameters

Name	Type	Required	Description
space_token	string	Yes	Public token of the space where task is created

You can get the space_token by hitting the Get All Spaces API. The token field in the response is your Space Token.

Headers

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

Request Body

Field	Type	Required	Description
pilot	string	Yes	Agent/pilot handle to assign the task
documents	array	Yes	Array of document objects with task data
context	string	No	Additional context for the task
schedule	object	No	Schedule configuration (type: “now”)

Example Request

POST /api/v2/platform/spaces/your-space-token/tasks/
Headers:
  Authorization: Token your-api-token
  Content-Type: application/json

Body:
{
  "pilot": "space-agent-f1o3qjm1y7q1avvuynv4vprb1",
  "documents": [
    {
      "name": "John Doe",
      "time": null,
      "email": "[email protected]",
      "contact_number": "1234567890",
      "alternate_number": "9876543210",
      "occupation": "Developer",
      "company_name": "TechCorp",
      "address": "123/456 Main Street",
      "about": "Software Developer",
      "context": "Follow up call",
      "multi_select": "multi",
      "created": "2025-10-30T05:44:56",
      "labels": ["Interested"],
      "title": "Document Title",
      "description": "Description text",
      "document_id": "6902fb5840a736e125e80ebc"
    }
  ],
  "context": "Call the lead and discuss the project requirements.",
  "schedule": {
    "type": "now"
  }
}

Document Object Fields

Field	Type	Required	Description
name	string	Yes	Contact name
email	string	No	Contact email
contact_number	string	Yes	Primary contact number
alternate_number	string	No	Alternate contact number
occupation	string	No	Contact’s occupation
company_name	string	No	Contact’s company
address	string	No	Contact’s address
about	string	No	About the contact
context	string	No	Additional context for the call
labels	array	No	Labels/tags for the document
title	string	No	Document title
description	string	No	Document description
document_id	string	No	Unique document identifier

Success Response (200)

{
  "status_code": 200,
  "message": "Task Created Successfully",
  "data": {
    "run_id": "Rf36292fceaa211ef8e2a91681c5ad3ab",
    "space_id": "321",
    "status": "pending",
    "created": "2025-11-17T10:30:00.000000",
    "_id": "67aeecb2851179ff81e48f64"
  }
}

Response Fields

Field	Type	Description
status_code	integer	HTTP status code
message	string	Response message
data	object	Created task details

Data Object Fields

Field	Type	Description
run_id	string	Created run identifier
space_id	string	Space identifier
status	string	Task status (initially `pending`)
created	string	Task creation timestamp
_id	string	Internal task document ID

Error Response (206 — Validation / Creation Failed)

{
  "message": "Task creation failed",
  "errors": "Detailed error description"
}

Get All Agents

Retrieve detailed information for all registered agents, helping you view and manage agent records within the system.

GET /api/v2/platform/agents/

Headers

Name	Type	Required	Description
Authorization	string	Yes	API Key format: `Token <token>`
Org-Handle	string	Yes	Organization domain handle

You can get the Org-Handle by hitting the Get All Organizations API. The domain_handle field in the response is your Org-Handle.

Example Request

GET /api/v2/platform/agents/
Headers:
  Authorization: Token your-api-token
  Org-Handle: your-org-handle

Success Response (200)

{
  "count": 94,
  "status_code": 200,
  "message": "Agents fetched successfully",
  "data": [
    {
      "handle": "space-agent-8qmk42nslp91wrh3dz7btxc4",
      "name": "General Agentic",
      "type": "Voice",
      "state": "published",
      "description": "Hi,",
      "purpose": ""
    }
  ]
}

Response Fields

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

Agent Object Fields

Field	Type	Description
handle	string	Unique agent handle/identifier
name	string	Agent display name
type	string	Agent type: `Voice`, `Chat`, etc.
state	string	Agent state: `published`, `draft`, `archived`
description	string	Agent description
purpose	string	Agent purpose/use case

Error Response (401 — Unauthorized)

{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

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, attachments, and execution details.

GET /api/v2/platform/agents/{handle}/tasks/

Path Parameters

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

The handle is the agent handle. You can get it 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`

Example Request

GET /api/v2/platform/agents/sales-agent-v1/tasks/
Headers:
  Authorization: Token your-api-token
  Content-Type: application/json

Success Response (200)

{
  "count": 1,
  "status_code": 200,
  "message": "Tasks Fetched Successfully",
  "data": [
    {
      "_id": "example123456789",
      "space_id": "999",
      "thread_id": null,
      "user": "101",
      "user_org_id": "501",
      "user_info": {
        "id": "101",
        "email": "[email protected]",
        "full_name": "Demo User",
        "user_token": "DEMO123TOKEN456"
      },
      "created": "2025-01-10T10:20:30.000000",
      "modified": "2025-01-10T10:25:30.000000",
      "task_id": "TASK123456789",
      "run_id": "RUN123456789",
      "collection_ref": "collection_data_DEMO123456",
      "task": {
        "objective": "call"
      },
      "input": {
        "name": "John Doe",
        "about": "Software Developer",
        "email": "[email protected]",
        "address": "New Delhi",
        "occupation": "Developer",
        "company_name": "TechCorp",
        "contact_number": "9876543210",
        "created": "2025-01-01T12:00:00.000000",
        "context": "Policy Number 123456789, Amount Rupees ten thousand, Due Date 10th March 2025"
      },
      "output": {},
      "attachments": [],
      "assignee": "sales-agent-v1",
      "status": "pending",
      "execution_type": "call",
      "ref_id": "doc-123456"
    }
  ]
}

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
space_id	string	Space identifier
thread_id	string	Thread identifier (null if not applicable)
user	string	User ID who created the task
user_org_id	string	Organization ID of the user
user_info	object	User details (id, email, full_name, token)
created	string	Task creation timestamp
modified	string	Last modified timestamp
task_id	string	Unique task identifier
run_id	string	Parent run identifier
collection_ref	string	Reference to the data collection
task	object	Task definition with objective
input	object	Input data for the task
output	object	Task output (empty if pending)
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

Error Response (206 — Tasks Fetch Failed)

{
  "message": "Error fetching tasks",
  "errors": "Detailed error description"
}

Error Response (404 — Agent Not Found)

{
  "message": "Agent not found"
}

Get Tasks by Space Token

Fetch all tasks for a specific space using the space_token. Supports pagination with page and query parameters for efficient data retrieval.

GET /api/v2/platform/spaces/{space_token}/tasks/

Path Parameters

Name	Type	Required	Description
space_token	string	Yes	Public token identifying the workspace

You can get the space_token by hitting the Get All Spaces API. The token field in the response is your Space Token.

Query Parameters (Optional)

Name	Type	Required	Description
page	int	No	Page number (default = 1)
page_size	int	No	Number of tasks per page (default = 20)

Headers

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

Example Request

GET /api/v2/platform/spaces/your-space-token/tasks/?page=1&page_size=20
Headers:
  Authorization: Token your-api-token
  Content-Type: application/json

Success Response (200)

{
  "count": 2,
  "status_code": 200,
  "message": "Tasks Fetched Successfully",
  "data": [
    {
      "_id": "space_task_id_001",
      "space_id": "999",
      "thread_id": null,
      "user": "456",
      "user_org_id": "789",
      "user_info": {
        "id": "456",
        "email": "[email protected]",
        "full_name": "Sarah Johnson",
        "user_token": "SPACE_TOKEN_ABC123"
      },
      "created": "2025-01-15T14:30:00.000000",
      "modified": "2025-01-15T14:35:00.000000",
      "task_id": "TASK_SPACE_456789",
      "run_id": "RUN_SPACE_987654",
      "collection_ref": "collection_data_SPACE123456",
      "task": {
        "objective": "Follow up with potential clients for product demo"
      },
      "input": {
        "name": "Rajesh Kumar",
        "contact_number": "+919988776655",
        "email": "[email protected]",
        "address": "Bangalore, Karnataka, India",
        "occupation": "CTO",
        "company_name": "TechStart Solutions",
        "context": "Interested in AI automation tools for their startup. Budget: 50K-1L, Timeline: Q1 2025"
      },
      "output": {
        "call_id": "019aa6a9-809f-7ddb-b110-7a16167cb632",
        "customer": "Cust 1",
        "contact_number": "70000380188",
        "call_end_reason": "customer-ended-call",
        "recording_url": "https://store.unpod.ai/media/private/high-call-recordings/...",
        "transcript": [
          {
            "role": "user",
            "content": "And reason for calling",
            "user_id": "unknown",
            "timestamp": ""
          },
          {
            "role": "assistant",
            "content": "Hello?",
            "user_id": null,
            "timestamp": ""
          }
        ],
        "start_time": "2025-11-21 13:45:20",
        "end_time": "2025-11-21 13:46:36",
        "assistant_number": "+919949883072",
        "call_summary": "An AI representative called regarding the premium project inquiry...",
        "duration": 76.769,
        "cost": 0.139,
        "post_call_data": {
          "classification": {
            "labels": ["Interested"],
            "summary": "The agent called to discuss the project. The user expressed interest."
          },
          "summary": {
            "status": "Call Back",
            "summary": "The call involved an introduction and inquiry about the project.",
            "name": "N/A",
            "contact": "N/A",
            "callback_datetime": "N/A",
            "hours_from_now": "N/A"
          },
          "success_evaluator": "{\"score\": 5, \"reason\": \"...\"}",
          "call_back": null,
          "follow_up": null,
          "structured_data": "{\"customer_name\": null, ...}",
          "webhook_data": null,
          "call_evaluation": []
        },
        "metadata": {
          "cost": 0.139,
          "type": "outboundPhoneCall",
          "usage": {}
        }
      },
      "attachments": [],
      "assignee": "sales-bot-v3",
      "status": "completed",
      "execution_type": "call",
      "ref_id": "lead_doc_456789"
    },
    {
      "_id": "space_task_id_002",
      "space_id": "999",
      "thread_id": null,
      "user": "456",
      "user_org_id": "789",
      "user_info": {
        "id": "456",
        "email": "[email protected]",
        "full_name": "Sarah Johnson",
        "user_token": "SPACE_TOKEN_ABC123"
      },
      "created": "2025-01-15T13:20:00.000000",
      "modified": "2025-01-15T13:20:00.000000",
      "task_id": "TASK_SPACE_456790",
      "run_id": "RUN_SPACE_987655",
      "collection_ref": "collection_data_SPACE123456",
      "task": {
        "objective": "Payment reminder for invoice #INV-2025-001"
      },
      "input": {
        "name": "Priya Sharma",
        "contact_number": "+919876543210",
        "email": "[email protected]",
        "address": "Mumbai, Maharashtra",
        "occupation": "Finance Manager",
        "company_name": "Global Enterprises Ltd",
        "context": "Pending invoice INV-2025-001 amount Rs. 45,000, due date 20th Jan 2025"
      },
      "output": {},
      "attachments": [],
      "assignee": "payment-bot-v1",
      "status": "pending",
      "execution_type": "call",
      "ref_id": "invoice_doc_001"
    }
  ]
}

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
space_id	string	Space identifier
thread_id	string	Thread identifier (null if not applicable)
user	string	User ID who created the task
user_org_id	string	Organization ID of the user
user_info	object	User details (id, email, full_name, token)
created	string	Task creation timestamp
modified	string	Last modified timestamp
task_id	string	Unique task identifier
run_id	string	Parent run identifier
collection_ref	string	Reference to the data collection
task	object	Task definition with objective
input	object	Input data for the task
output	object	Task output (empty if pending)
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

Output Object Fields

Field	Type	Description
call_id	string	Unique call identifier
customer	string	Customer name
contact_number	string	Contact phone number
call_end_reason	string	Reason for call ending
recording_url	string	URL to call recording
transcript	array	Array of conversation messages
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
cost	number	Cost of the call in USD
post_call_data	object	Post-call analysis data
metadata	object	Additional metadata (cost, type, usage)

Error Response (206 — Tasks Fetch Failed)

{
  "message": "Error fetching tasks",
  "errors": "Detailed error description"
}

Common Error Codes

Status Code	Description
200	Success - Data fetched/created 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 or Space 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 getTasksByAgent = async (agentHandle) => {
  const response = await axios.get(
    `https://unpod.dev/api/v2/platform/agents/${agentHandle}/tasks/`,
    { headers }
  );
  console.log(`Total tasks: ${response.data.count}`);
  return response.data.data;
};

// Get tasks by space token with pagination
const getTasksBySpace = async (spaceToken, page = 1, pageSize = 20) => {
  const response = await axios.get(
    `https://unpod.dev/api/v2/platform/spaces/${spaceToken}/tasks/?page=${page}&page_size=${pageSize}`,
    { headers }
  );
  console.log(`Total tasks: ${response.data.count}`);
  return response.data.data;
};

// Create a task in a space
const createTask = async (spaceToken, pilot, documents, context) => {
  const response = await axios.post(
    `https://unpod.dev/api/v2/platform/spaces/${spaceToken}/tasks/`,
    {
      pilot,
      documents,
      context,
      schedule: { type: 'now' }
    },
    { headers }
  );
  console.log(`Task created: ${response.data.data.run_id}`);
  return response.data.data;
};

// Example usage
getTasksByAgent('sales-agent-v1');

Best Practices

Pagination: Use page and page_size parameters for efficient data retrieval
Agent Handle: Ensure you’re using the correct agent handle for task assignment
Document Fields: Include all required document fields (name, contact_number)
Error Handling: Always handle potential errors and edge cases
Security: Keep API tokens secure and rotate them regularly

Get Started

Space

Provider

Telephony

Execution

Logs

​Tasks API

​Create a Task in a Space

​Path Parameters

​Headers

​Request Body

​Example Request

​Document Object Fields

​Success Response (200)

​Response Fields

​Data Object Fields

​Error Response (206 — Validation / Creation Failed)

​Get All Agents

​Headers

​Example Request

​Success Response (200)

​Response Fields

​Agent Object Fields

​Error Response (401 — Unauthorized)

​Get Tasks by Agent Handle

​Path Parameters

​Headers

​Example Request

​Success Response (200)

​Response Fields

​Task Object Fields

​Error Response (206 — Tasks Fetch Failed)

​Error Response (404 — Agent Not Found)

​Get Tasks by Space Token

​Path Parameters

​Query Parameters (Optional)

​Headers

​Example Request

​Success Response (200)

​Response Fields

​Task Object Fields

​Output Object Fields

​Error Response (206 — Tasks Fetch Failed)

​Common Error Codes

​Code Examples

​Best Practices

Tasks API

Create a Task in a Space

Path Parameters

Headers

Request Body

Example Request

Document Object Fields

Success Response (200)

Response Fields

Data Object Fields

Error Response (206 — Validation / Creation Failed)

Get All Agents

Headers

Example Request

Success Response (200)

Response Fields

Agent Object Fields

Error Response (401 — Unauthorized)

Get Tasks by Agent Handle

Path Parameters

Headers

Example Request

Success Response (200)

Response Fields

Task Object Fields

Error Response (206 — Tasks Fetch Failed)

Error Response (404 — Agent Not Found)

Get Tasks by Space Token

Path Parameters

Query Parameters (Optional)

Headers

Example Request

Success Response (200)

Response Fields

Task Object Fields

Output Object Fields

Error Response (206 — Tasks Fetch Failed)

Common Error Codes

Code Examples

Best Practices