History API
The History API provides access to historical data for tasks and steps, enabling you to track the complete lifecycle and performance of your AI agent workflows.
Overview
The History API allows you to:
- Track task progression: View complete task execution history
- Monitor step details: Access detailed step execution logs
- Analyze performance: Review timing and success metrics
- Debug issues: Investigate failed tasks and steps
- Generate reports: Create usage and performance reports
Endpoints
Get Task History
GET /history/{task_id}
Retrieves the complete history for a specific task, including all steps and their execution details.
Parameters
task_id(path, required): Task ID
Headers
Authorization: Bearer YOUR_API_KEYResponse
{
"status": "success",
"message": "Task history retrieved successfully",
"data": [
{
"task_id": "task_abc123",
"task_name": "Build REST API with Authentication",
"status": "completed",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T14:45:00Z",
"duration": "4h 15m",
"steps": [
{
"step_id": "step_xyz789",
"step_name": "Generate API endpoints",
"agent": "code_agent",
"model": "anthropic/claude-3-sonnet",
"status": "completed",
"started_at": "2024-01-15T10:35:00Z",
"completed_at": "2024-01-15T11:20:00Z",
"duration": "45m",
"tokens_used": 1250,
"tools_used": ["write_to_file", "execute_command"]
},
{
"step_id": "step_uvw456",
"step_name": "Write unit tests",
"agent": "test_agent",
"model": "openai/gpt-4",
"status": "completed",
"started_at": "2024-01-15T11:25:00Z",
"completed_at": "2024-01-15T12:10:00Z",
"duration": "45m",
"tokens_used": 980,
"tools_used": ["write_test_file", "execute_command"]
}
],
"total_tokens": 2230,
"total_steps": 2,
"success_rate": 100
}
]
}Get All Task History
GET /history
Retrieves history for all tasks belonging to the authenticated user.
Query Parameters
limit(optional): Maximum number of tasks to return (default: 50)offset(optional): Number of tasks to skip (default: 0)status(optional): Filter by task status (created, in_progress, completed, failed, cancelled)from_date(optional): Filter tasks created after this date (ISO 8601 format)to_date(optional): Filter tasks created before this date (ISO 8601 format)
Headers
Authorization: Bearer YOUR_API_KEYResponse
{
"status": "success",
"message": "Task history retrieved successfully",
"data": [
{
"task_id": "task_abc123",
"task_name": "Build REST API with Authentication",
"status": "completed",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T14:45:00Z",
"duration": "4h 15m",
"total_steps": 2,
"success_rate": 100
},
{
"task_id": "task_def456",
"task_name": "Generate Test Suite",
"status": "completed",
"created_at": "2024-01-14T09:15:00Z",
"completed_at": "2024-01-14T12:30:00Z",
"duration": "3h 15m",
"total_steps": 3,
"success_rate": 100
}
],
"pagination": {
"total": 25,
"limit": 50,
"offset": 0,
"has_more": false
}
}History Data Structure
Task History Fields
| Field | Type | Description |
|---|---|---|
task_id | string | Unique task identifier |
task_name | string | Human-readable task name |
status | string | Final task status |
created_at | string | Task creation timestamp (ISO 8601) |
completed_at | string | Task completion timestamp (ISO 8601) |
duration | string | Human-readable duration |
total_steps | number | Number of steps in the task |
success_rate | number | Percentage of successful steps |
total_tokens | number | Total tokens consumed |
Step History Fields
| Field | Type | Description |
|---|---|---|
step_id | string | Unique step identifier |
step_name | string | Human-readable step name |
agent | string | Agent that executed the step |
model | string | AI model used for the step |
status | string | Final step status |
started_at | string | Step start timestamp (ISO 8601) |
completed_at | string | Step completion timestamp (ISO 8601) |
duration | string | Human-readable duration |
tokens_used | number | Tokens consumed by this step |
tools_used | array | List of tools used during execution |
Usage Examples
Get Recent Task History
curl -X GET "https://api.dispersl.com/v1/history?limit=10&status=completed" \
-H "Authorization: Bearer YOUR_API_KEY"Get Task History for Date Range
curl -X GET "https://api.dispersl.com/v1/history?from_date=2024-01-01T00:00:00Z&to_date=2024-01-31T23:59:59Z" \
-H "Authorization: Bearer YOUR_API_KEY"Get Detailed Task History
curl -X GET "https://api.dispersl.com/v1/history/task_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"Performance Analytics
Task Success Rates
async function getTaskSuccessRate(fromDate, toDate) {
const response = await fetch(
`/api/history?from_date=${fromDate}&to_date=${toDate}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const history = await response.json();
const tasks = history.data;
const completed = tasks.filter(t => t.status === 'completed').length;
const total = tasks.length;
return {
successRate: (completed / total) * 100,
totalTasks: total,
completedTasks: completed
};
}Average Task Duration
async function getAverageTaskDuration() {
const response = await fetch('/api/history?status=completed', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const history = await response.json();
const tasks = history.data;
const durations = tasks.map(task => {
// Convert duration string to minutes
const match = task.duration.match(/(\d+)h (\d+)m/);
if (match) {
return parseInt(match[1]) * 60 + parseInt(match[2]);
}
return 0;
});
const average = durations.reduce((a, b) => a + b, 0) / durations.length;
return `${Math.floor(average / 60)}h ${average % 60}m`;
}Best Practices
Data Retention
- History data is retained for 90 days on Free tier
- Pro and Enterprise tiers have extended retention periods
- Export important historical data for long-term storage
Performance Monitoring
- Track success rates: Monitor task completion rates over time
- Analyze duration trends: Identify performance improvements or regressions
- Monitor token usage: Track AI model consumption patterns
- Review tool usage: Understand which tools are most effective
Debugging Failed Tasks
- Check step details: Review individual step failures
- Analyze error patterns: Look for common failure modes
- Review tool usage: Ensure appropriate tools were selected
- Check model performance: Compare success rates across different models
Error Responses
- 400: Invalid query parameters or date format
- 401: No Bearer token provided
- 404: Task not found
- 500: Internal server error
Rate Limits
History API endpoints have the same rate limits as other API endpoints:
- Free: 100 requests per hour
- Pro: 1,000 requests per hour
- Enterprise: Custom limits
Data Export
For bulk data analysis, consider using the export functionality:
# Export task history as CSV
curl -X GET "https://api.dispersl.com/v1/history/export?format=csv&from_date=2024-01-01T00:00:00Z" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o task_history.csv
# Export as JSON
curl -X GET "https://api.dispersl.com/v1/history/export?format=json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o task_history.json