Runs API

The Runs API allows you to manage and monitor execution runs in your Unpod platform. A run represents a batch execution or group of tasks within a space.

How to Get Your Space Token

Follow these steps to obtain your Space Token from the Unpod Dashboard:

Login to the Unpod Dashboard
On the left sidebar, click on the Conversation tab
Click on the Settings icon
You’ll see the Space Token option
Click on it to copy the Space Token

Each space has a unique token. Make sure you’re using the correct space token for your API requests.

Get All Runs in a Space

Retrieve all runs associated with a specific space. A run represents a batch execution or group of tasks. This endpoint returns run details including run ID, status, timestamps, and associated user metadata.

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

Path Parameters

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

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/space_abc123xyz/runs/
Headers:
  Authorization: Token your-api-token
  Content-Type: application/json

Success Response (200)

{
  "count": 1716,
  "status_code": 200,
  "message": "Runs Fetched Successfully",
  "data": [
    {
      "space_id": "346",
      "user": "38",
      "thread_id": null,
      "run_id": "R40fe5eface1511f082ac156368e7acc4",
      "collection_ref": "collection_data_F1O3QJM1Y7Q1AVVUYNV4VPRB",
      "run_mode": "dev",
      "status": "completed",
      "batch_count": 1,
      "created": "2025-11-30T17:51:52",
      "modified": "2025-11-30T17:51:52"
    }
  ]
}

Response Fields

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

Run Object Fields

Field	Type	Description
space_id	string	Space identifier
user	string	User ID who created the run
thread_id	string	Thread identifier (null if not applicable)
run_id	string	Unique run identifier
collection_ref	string	Reference to the data collection
run_mode	string	Execution mode: `dev`, `prod`
status	string	Run status: `completed`, `running`, `failed`
batch_count	integer	Number of batches in the run
created	string	Run creation timestamp
modified	string	Last modified timestamp

Error Response (206 — Fetch Failed)

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

Get Detailed Tasks for a Specific Run

Fetches all tasks for a specific run, including complete input, output, call transcript, costs, analysis, artifacts, and provider metadata. This endpoint is used when you need deep inspection of how a run executed each task.

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

Path Parameters

Name	Type	Required	Description
space_token	string	Yes	Public token of the space
run_id	string	Yes	The run ID whose tasks to retrieve

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/space_abc123xyz/runs/R40fe5eface1511f082ac156368e7acc4/tasks/
Headers:
  Authorization: Token your-api-token
  Content-Type: application/json

Success Response (200)

{
  "count": 1,
  "status_code": 200,
  "message": "Tasks Fetched Successfully",
  "data": [
    {
      "space_id": "346",
      "thread_id": null,
      "user": "261",
      "user_org_id": "22",
      "user_info": {
        "id": "261",
        "email": "[email protected]",
        "full_name": "John Doe",
        "user_token": "JY60XSSVVPTV5W5A"
      },
      "run_id": "R0e3294d4cc4211f082ac156368e7acc4",
      "task_id": "T0e3294d5cc4211f082ac156368e7acc4",
      "collection_ref": "collection_data_F1O3QJM1Y7Q1AVVUYNV4VPRB",
      "execution_type": "call",
      "task": {
        "objective": "hey"
      },
      "input": {
        "document_id": "692974344eb028916272c240",
        "name": "John Doe",
        "contact_number": "9876688992",
        "created": "2025-11-28T10:06:44",
        "token": "F1O3QJM1Y7Q1AVVUYNV4VPRB",
        "vapi_agent_id": "6a683958-27ab-4ac5-8b0f-52dae3892efe",
        "number_id": "2d81624a-a0ec-4459-9399-cf71fb21be06",
        "quality": "high"
      },
      "output": {
        "id": "call-uuid-001",
        "assistantId": "assistant-123",
        "phoneNumberId": "phone-456",
        "type": "outbound",
        "startedAt": "2025-11-17T12:05:00.000Z",
        "endedAt": "2025-11-17T12:10:00.000Z",
        "transcript": "Agent: Hello, this is calling to confirm...\nCustomer: Yes, confirmed.",
        "recordingUrl": "https://example.com/recordings/rec123.mp3",
        "summary": "Customer confirmed the appointment for tomorrow at 2 PM",
        "createdAt": "2025-11-17T12:05:00.000Z",
        "updatedAt": "2025-11-17T12:10:00.000Z",
        "orgId": "org-789",
        "cost": 0.45,
        "customer": {
          "number": "+1234567890",
          "name": "Alice Smith"
        }
      },
      "created": "2025-11-28T10:07:32",
      "modified": "2025-11-28T12:04:08"
    }
  ]
}

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
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)
run_id	string	Parent run identifier
task_id	string	Unique task identifier
collection_ref	string	Reference to the data collection
execution_type	string	Type of execution: `call`, `email`, etc.
task	object	Task definition with objective
input	object	Input data for the task
output	object	Task output including call details
created	string	Task creation timestamp
modified	string	Last modified timestamp

Input Object Fields

Field	Type	Description
document_id	string	Document identifier
name	string	Contact name
contact_number	string	Contact phone number
created	string	Input creation timestamp
token	string	Collection token
vapi_agent_id	string	Vapi agent identifier
number_id	string	Number identifier
quality	string	Call quality setting: `high`, `low`

Output Object Fields

Field	Type	Description
id	string	Unique call identifier
assistantId	string	Assistant identifier
phoneNumberId	string	Phone number identifier
type	string	Call type: `outbound`, `inbound`
startedAt	string	Call start timestamp
endedAt	string	Call end timestamp
transcript	string	Call transcript
recordingUrl	string	URL to call recording
summary	string	AI-generated call summary
createdAt	string	Record creation timestamp
updatedAt	string	Record update timestamp
orgId	string	Organization identifier
cost	number	Cost of the call in USD
customer	object	Customer details (number, name)

Error Response (206 — Business Logic Error)

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

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 - Space or Run 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 all runs in a space
const fetchRuns = async (spaceToken) => {
  const response = await axios.get(
    `https://unpod.dev/api/v2/platform/spaces/${spaceToken}/runs/`,
    { headers }
  );

  console.log(`Total runs: ${response.data.count}`);
  response.data.data.forEach(run => {
    console.log(`Run ${run.run_id}: ${run.status} (${run.batch_count} batches)`);
  });
  return response.data.data;
};

// Get tasks for a specific run
const fetchRunTasks = async (spaceToken, runId) => {
  const response = await axios.get(
    `https://unpod.dev/api/v2/platform/spaces/${spaceToken}/runs/${runId}/tasks/`,
    { headers }
  );

  console.log(`Total tasks: ${response.data.count}`);
  response.data.data.forEach(task => {
    console.log(`Task ${task.task_id}: ${task.execution_type}`);
    if (task.output?.summary) {
      console.log(`  Summary: ${task.output.summary}`);
    }
  });
  return response.data.data;
};

// Example usage
fetchRuns('your-space-token');

Best Practices

Space Token: Always use the correct space token for your API requests
Pagination: For spaces with many runs, implement proper pagination handling
Error Handling: Always handle potential errors and edge cases
Filtering: Use status filters to focus on specific run outcomes
Security: Keep API tokens secure and rotate them regularly

Get Started

Execution

Telephony

Provider

Logs

Space

Runs

Runs API

How to Get Your Space Token

Get All Runs in a Space

Path Parameters

Headers

Example Request

Success Response (200)

Response Fields

Run Object Fields

Error Response (206 — Fetch Failed)

Get Detailed Tasks for a Specific Run

Path Parameters

Headers

Example Request

Success Response (200)

Response Fields

Task Object Fields

Input Object Fields

Output Object Fields

Error Response (206 — Business Logic Error)

Common Error Codes

Code Examples

Best Practices

Get Started

Execution

Telephony

Provider

Logs

Space

​Runs API

​How to Get Your Space Token

​Get All Runs in a Space

​Path Parameters

​Headers

​Example Request

​Success Response (200)

​Response Fields

​Run Object Fields

​Error Response (206 — Fetch Failed)

​Get Detailed Tasks for a Specific Run

​Path Parameters

​Headers

​Example Request

​Success Response (200)

​Response Fields

​Task Object Fields

​Input Object Fields

​Output Object Fields

​Error Response (206 — Business Logic Error)

​Common Error Codes

​Code Examples

​Best Practices

Runs API

How to Get Your Space Token

Get All Runs in a Space

Path Parameters

Headers

Example Request

Success Response (200)

Response Fields

Run Object Fields

Error Response (206 — Fetch Failed)

Get Detailed Tasks for a Specific Run

Path Parameters

Headers

Example Request

Success Response (200)

Response Fields

Task Object Fields

Input Object Fields

Output Object Fields

Error Response (206 — Business Logic Error)

Common Error Codes

Code Examples

Best Practices