Skip to main content

​
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.
Prerequisites: Make sure you have your API Token. See Authentication for details.

​
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

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

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Content-TypestringYesapplication/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": 9,
    "status_code": 200,
    "message": "Runs Fetched Successfully",
    "data": [
        {
            "run_id": "Recac64fe03e911f1878d43cd8a99e069",
            "collection_ref": "collection_data_SA2W8R6NZRK6C9PO3JSL1J85",
            "run_mode": "prefect",
            "status": "completed",
            "created": "2026-02-07T05:57:45",
            "modified": "2026-02-07T05:57:45"
        },
        {
            "run_id": "R6b653894fe9411f0878d43cd8a99e069",
            "collection_ref": "collection_data_SA2W8R6NZRK6C9PO3JSL1J85",
            "run_mode": "prefect",
            "status": "completed",
            "created": "2026-01-31T11:03:05",
            "modified": "2026-01-31T11:03:05"
        }
    ]
}

​
Response Fields

FieldTypeDescription
countintegerTotal number of runs
status_codeintegerHTTP status code
messagestringResponse message
dataarrayArray of run objects

​
Run Object Fields

FieldTypeDescription
run_idstringUnique run identifier
collection_refstringReference to the data collection
run_modestringExecution engine: prefect, etc.
statusstringRun status: completed, running, failed
createdstringRun creation timestamp
modifiedstringLast 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

NameTypeRequiredDescription
space_tokenstringYesPublic token of the space
run_idstringYesThe run ID whose tasks to retrieve

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Content-TypestringYesapplication/json
You can get the space_token by hitting the Get All Spaces API. The run_id can be obtained from the Get All Runs in a Space API response.

​
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": 9,
    "status_code": 200,
    "message": "Runs Fetched Successfully",
    "data": [
        {
            "run_id": "Recac64fe03e911f1878d43cd8a99e069",
            "collection_ref": "collection_data_SA2W8R6NZRK6C9PO3JSL1J85",
            "run_mode": "prefect",
            "status": "completed",
            "created": "2026-02-07T05:57:45",
            "modified": "2026-02-07T05:57:45"
        },
        {
            "run_id": "R6b653894fe9411f0878d43cd8a99e069",
            "collection_ref": "collection_data_SA2W8R6NZRK6C9PO3JSL1J85",
            "run_mode": "prefect",
            "status": "completed",
            "created": "2026-01-31T11:03:05",
            "modified": "2026-01-31T11:03:05"
        }
    ]
}

​
Response Fields

FieldTypeDescription
countintegerTotal number of tasks
status_codeintegerHTTP status code
messagestringResponse message
dataarrayArray of task objects

​
Task Object Fields

FieldTypeDescription
thread_idstringThread identifier
user_infoobjectUser details (email, full_name)
run_idstringParent run identifier
task_idstringUnique task identifier
execution_typestringType of execution: call, email, etc.
taskobjectTask definition with objective
inputobjectInput data for the task
outputobjectTask output including call details
createdstringTask creation timestamp
modifiedstringLast modified timestamp

​
Error Response (206 — Business Logic Error)

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

​
Common Error Codes

Status CodeDescription
200Success - Data fetched successfully
206Partial Content - Business logic error occurred
400Bad Request - Invalid parameters provided
401Unauthorized - Invalid or missing API token
403Forbidden - Access denied to the resource
404Not Found - Space or Run not found
500Internal 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

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