curl "https://api.orchestratorhq.com/api/sessions?limit=10&status=active" \
  -H "Authorization: Bearer orch_your_api_key_here"

{
  "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
  }
}
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

​
limit
integer
default:"25"
Number of sessions to return (1-100)
​
offset
integer
default:"0"
Number of sessions to skip for pagination
​
status
string
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

​
duration
string
required
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

Integration Guides

Learn how to integrate with specific automation frameworks

API Reference

Explore the complete API documentation