Skip to main content
GET
/
api
/
v2
/
platform
/
agents
/
{agent_handle}
/
executions
Get All Agent Executions
curl --request GET \
  --url http://localhost:3001/api/v2/platform/agents/{agent_handle}/executions/ \
  --header 'Authorization: <api-key>' \
  --header 'Org-Handle: <org-handle>'
{
  "count": 12,
  "status_code": 200,
  "message": "Executions fetched successfully",
  "data": [
    {
      "run_id": "Recac64fe03e911f1878d43cd8a99e069",
      "status": "completed",
      "total_tasks": 25,
      "completed_tasks": 23,
      "created": "2026-02-07T05:57:45Z"
    }
  ]
}

{
  "count": 12,
  "status_code": 200,
  "message": "Executions fetched successfully",
  "data": [
    {
      "run_id": "Recac64fe03e911f1878d43cd8a99e069",
      "status": "completed",
      "total_tasks": 25,
      "completed_tasks": 23,
      "created": "2026-02-07T05:57:45Z"
    }
  ]
}

​
Get All Agent Executions

Retrieve all execution runs associated with a specific agent. This endpoint provides a summary of each run including status, task counts, and timestamps — useful for monitoring agent performance and execution history.
Prerequisites: Make sure you have your API Token and Org-Handle ready. See Authentication for details.

​
Path Parameters

NameTypeRequiredDescription
agent_handlestringYesUnique 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

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Org-HandlestringYesOrganization 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.

​
Response Fields

FieldTypeDescription
countintegerTotal number of executions
status_codeintegerHTTP status code
messagestringResponse message
dataarrayArray of execution objects

​
Execution Object Fields

FieldTypeDescription
run_idstringUnique run identifier
statusstringRun status: completed, running, failed, pending
total_tasksintegerTotal number of tasks in the run
completed_tasksintegerNumber of successfully completed tasks
createdstringRun creation timestamp (ISO 8601)

​
Common Error Codes

Status CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters provided
401Unauthorized - Invalid or missing API token
403Forbidden - Access denied to the resource
404Not Found - Agent not found
500Internal Server Error - Server-side error

​
Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Org-Handle': 'your-org-handle'
};

// Get all executions for an agent
const getAgentExecutions = async (agentHandle) => {
  const response = await axios.get(
    `https://unpod.dev/api/v2/platform/agents/${agentHandle}/executions/`,
    { headers }
  );
  console.log(`Total executions: ${response.data.count}`);
  response.data.data.forEach(exec => {
    const completionRate = (exec.completed_tasks / exec.total_tasks * 100).toFixed(1);
    console.log(`Run ${exec.run_id}: ${exec.status} (${completionRate}% complete)`);
  });
  return response.data.data;
};

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

​
Best Practices

  1. Agent Handle: Use the exact agent handle from the Get All Agents response
  2. Completion Tracking: Calculate completed_tasks / total_tasks ratio to monitor run success rates
  3. Status Monitoring: Poll this endpoint to track long-running executions
  4. Error Handling: Always handle potential errors and edge cases
  5. 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"

Path Parameters

​
agent_handle
string
required
Example:

"sales-agent"

Response

List of executions for the agent