Create new browser sessions that can be accessed via VNC or Chrome DevTools Protocol (CDP) for automation and manual interaction.
Create Session Endpoint
curl -X POST https://api.orchestratorhq.com/api/sessions \
-H "Authorization: Bearer orch_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"session_name": "My Test Session",
"description": "Session for testing automation scripts",
"duration": "2h"
}'
Request Parameters
Human-readable name for the session. Helps identify sessions in the dashboard.
Optional description of the session purpose or use case.
Session duration in human-readable format (e.g., “2h”, “30m”, “1h30m”). Defaults to 2 hours if not specified.Examples: “30m”, “1h”, “2h30m”, “45m”
Session Status Values
Sessions progress through several states during their lifecycle:
| Status | Description |
|---|
active | Session is running and ready to use |
stopping | Session is being terminated |
stopped | Session has been terminated |
Note: When the API responds with a session, it is immediately active and ready for use.
Error Responses
{
"error": "INVALID_DURATION",
"message": "Duration must be between 1 minute and 24 hours",
"code": 400,
"context": {
"duration": "25h"
}
}
Common Error Codes
| Code | Error | Description |
|---|
400 | INVALID_DURATION | Duration format is invalid or out of range |
401 | UNAUTHORIZED | Invalid or missing API key |
402 | INSUFFICIENT_CREDITS | Not enough credits to create session |
429 | SESSION_LIMIT_EXCEEDED | Organization concurrent session limit reached |
503 | NO_SERVERS_AVAILABLE | No browser servers available |
Complete Example
Here’s a complete example that creates a session and connects using Playwright:
const { chromium } = require('playwright');
require('dotenv').config();
async function createAndConnectSession() {
try {
// Create session
const sessionResponse = await fetch('https://api.orchestratorhq.com/api/sessions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ORCH_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
session_name: 'Playwright Session',
duration: '1h'
})
});
const session = await sessionResponse.json();
// Print session details
console.log('Session Info:');
console.log(' id:', session.id);
console.log(' organization_id:', session.organization_id);
console.log(' session_name:', session.session_name);
console.log(' status:', session.status);
console.log(' vnc_url:', session.vnc_url);
console.log(' cdp_url:', session.cdp_url);
console.log(' expires_at:', session.expires_at);
// Use cdp_url from session creation response
const cdpUrl = session.cdp_url || (session.access_urls && session.access_urls.cdp_url);
if (!cdpUrl) {
console.error('No cdp_url found in session response!');
return;
}
// Connect to browser (session is active when API responds)
const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];
// Your automation code here
await page.goto('https://example.com');
console.log('Page title:', await page.title());
// The browser and session will remain open
// Remember to stop the session when done
} catch (error) {
console.error('Error:', error);
}
}
createAndConnectSession();
Next Steps
Once your session is active, you can connect to it using various automation tools:
