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"
  }'
{
  "error": "INVALID_DURATION",
  "message": "Duration must be between 1 minute and 24 hours",
  "code": 400,
  "context": {
    "duration": "25h"
  }
}
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

session_name
string
Human-readable name for the session. Helps identify sessions in the dashboard.
description
string
Optional description of the session purpose or use case.
duration
string
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:
StatusDescription
activeSession is running and ready to use
stoppingSession is being terminated
stoppedSession 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

CodeErrorDescription
400INVALID_DURATIONDuration format is invalid or out of range
401UNAUTHORIZEDInvalid or missing API key
402INSUFFICIENT_CREDITSNot enough credits to create session
429SESSION_LIMIT_EXCEEDEDOrganization concurrent session limit reached
503NO_SERVERS_AVAILABLENo 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: