Once you have active sessions, you can monitor their status, extend their duration, list all sessions, and stop them when no longer needed.
List All Sessions
Retrieve all sessions for your organization with pagination support:
curl "https://api.orchestratorhq.com/api/sessions?limit=10&status=active" \
-H "Authorization: Bearer orch_your_api_key_here"
Query Parameters
Number of sessions to return (1-100)
Number of sessions to skip for pagination
Filter sessions by status: creating, queued, active, stopping, stopped, failed
{
"sessions": [
{
"id": "sess_abc123def456",
"session_name": "My Test Session",
"status": "active",
"created_at": "2025-01-15T10:30:00Z",
"expires_at": "2025-01-15T12:30:00Z",
"last_accessed_at": "2025-01-15T11:15:00Z"
},
{
"id": "sess_def456ghi789",
"session_name": "Automation Session",
"status": "active",
"created_at": "2025-01-15T09:45:00Z",
"expires_at": "2025-01-15T11:45:00Z",
"last_accessed_at": "2025-01-15T11:10:00Z"
}
],
"total": 15,
"pagination": {
"limit": 25,
"offset": 0
}
}
Get Session Details
Retrieve detailed information about a specific session:
curl https://api.orchestratorhq.com/api/sessions/sess_abc123def456 \
-H "Authorization: Bearer orch_your_api_key_here"
{
"id": "sess_abc123def456",
"session_name": "My Test Session",
"description": "Session for testing automation scripts",
"status": "active",
"user_id": "user_123",
"organization_id": "org_456",
"organization_role": "member",
"created_at": "2025-01-15T10:30:00Z",
"started_at": "2025-01-15T10:31:00Z",
"last_accessed_at": "2025-01-15T11:15:00Z",
"expires_at": "2025-01-15T12:30:00Z",
"vnc_url": "wss://browser-node-1.orchestratorhq.com:6080/websockify",
"cdp_url": "ws://browser-node-1.orchestratorhq.com:9222/devtools/browser/abc123",
"vnc_password": "secure_password_123",
"autoscaler_workload_id": "workload_789",
"autoscaler_server_id": "server_101",
"autoscaler_server_ip": "10.0.1.50"
}
Extend Session Duration
Extend the duration of an active session to prevent it from expiring:
curl -X POST https://api.orchestratorhq.com/api/sessions/sess_abc123def456/extend \
-H "Authorization: Bearer orch_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"duration": "30m"}'
Request Parameters
Additional time to add to the session in human-readable format (e.g., “30m”, “1h”, “2h30m”)
{
"id": "sess_abc123def456",
"session_name": "My Test Session",
"status": "active",
"expires_at": "2025-01-15T13:00:00Z",
"message": "Session extended by 30 minutes"
}
Stop Session
Terminate a running session and release its resources:
curl -X DELETE https://api.orchestratorhq.com/api/sessions/sess_abc123def456 \
-H "Authorization: Bearer orch_your_api_key_here"
{
"message": "Session stopped successfully",
"session_id": "sess_abc123def456"
}
System Status
Check the overall system status and autoscaler pool information:
curl https://api.orchestratorhq.com/api/status \
-H "Authorization: Bearer orch_your_api_key_here"
{
"autoscaler": {
"status": "healthy",
"pool_status": {
"total": 10,
"idle": 3,
"busy": 5,
"provisioning": 1,
"launching": 1,
"terminating": 0
}
},
"current_load": {
"active_sessions": 5,
"organization_id": "org_456"
},
"timestamp": "2025-01-15T11:30:00Z"
}
Health Check
Simple health check endpoint for monitoring:
curl https://api.orchestratorhq.com/api/health
{
"status": "healthy",
"service": "orchestrator-api",
"version": "1.0.0",
"timestamp": "2025-01-15T11:30:00Z",
"dependencies": {
"database": "healthy",
"autoscaler": "healthy"
}
}
Session Monitoring Example
Here’s a complete example that monitors multiple sessions:
async function monitorSessions() {
try {
// Get all active sessions
const response = await fetch('https://api.orchestratorhq.com/api/sessions?status=active', {
headers: {
'Authorization': 'Bearer orch_your_api_key_here'
}
});
const data = await response.json();
console.log(`Monitoring ${data.sessions.length} active sessions`);
for (const session of data.sessions) {
const expiresAt = new Date(session.expires_at);
const now = new Date();
const timeLeft = Math.round((expiresAt - now) / 1000 / 60); // minutes
console.log(`Session ${session.id}:`);
console.log(` Name: ${session.session_name}`);
console.log(` Status: ${session.status}`);
console.log(` Time left: ${timeLeft} minutes`);
// Extend sessions that are about to expire
if (timeLeft < 10 && timeLeft > 0) {
console.log(` Extending session ${session.id}...`);
await fetch(`https://api.orchestratorhq.com/api/sessions/${session.id}/extend`, {
method: 'POST',
headers: {
'Authorization': 'Bearer orch_your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({ duration: '30m' })
});
console.log(` Extended by 30 minutes`);
}
}
} catch (error) {
console.error('Error monitoring sessions:', error);
}
}
// Run monitoring every 5 minutes
setInterval(monitorSessions, 5 * 60 * 1000);
Error Handling
Common errors when managing sessions:
{
"error": "SESSION_NOT_FOUND",
"message": "Session with ID sess_abc123def456 not found",
"code": 404,
"context": {
"session_id": "sess_abc123def456"
}
}
Best Practices
Monitor Expiration
Regularly check session expiration times and extend sessions before they expire.
Clean Up Resources
Always stop sessions when finished to avoid unnecessary charges.
Handle Failures
Implement proper error handling for session state transitions and network issues.
Use Pagination
When listing many sessions, use pagination to avoid timeouts and improve performance.
Next Steps
