Sessions API

TL;DR

The Sessions API manages the lifecycle of remote machine sessions in CMDOP. List, view, and monitor sessions with statuses like PENDING, CONNECTED, GRACE_PERIOD, and DISCONNECTED. Retrieve attached clients, command history, and real-time telemetry metrics (CPU, memory, disk, network). Sessions emit webhook events for state changes.

How do I list sessions?


GET /v1/sessions

What query parameters are supported?

Parameter	Type	Description
`status`	string	Filter by status (PENDING, CONNECTED, GRACE_PERIOD, DISCONNECTED)
`machine_id`	string	Filter by machine ID
`machine_hostname`	string	Filter by hostname
`limit`	integer	Max results (default 20, max 100)
`offset`	integer	Pagination offset

Example


# List only connected sessions, returning up to 10 results
curl "https://api.cmdop.com/v1/sessions?status=CONNECTED&limit=10" \
  -H "Authorization: Bearer cmd_xxx"

Response


{
  "data": [
    {
      "session_id": "sess_abc123",
      "status": "CONNECTED",
      "machine_id": "mach_xyz789",
      "machine_hostname": "prod-server",
      "workspace_id": "ws_acme",
      "created_at": "2026-02-14T10:00:00Z",
      "connected_at": "2026-02-14T10:00:05Z",
      "last_heartbeat_at": "2026-02-14T10:30:00Z",
      "attached_clients": 2
    }
  ],
  "meta": {
    "total": 5,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

How do I get a specific session?


GET /v1/sessions/:session_id

Example


# Retrieve full session details including attached clients and telemetry
curl "https://api.cmdop.com/v1/sessions/sess_abc123" \
  -H "Authorization: Bearer cmd_xxx"

Response


{
  "data": {
    "session_id": "sess_abc123",
    "status": "CONNECTED",
    "machine_id": "mach_xyz789",
    "machine_hostname": "prod-server",
    "workspace_id": "ws_acme",
    "created_at": "2026-02-14T10:00:00Z",
    "connected_at": "2026-02-14T10:00:05Z",
    "last_heartbeat_at": "2026-02-14T10:30:00Z",
    "attached_clients": [
      {
        "client_id": "cli_111",
        "user_email": "[email protected]",
        "mode": "operator",
        "attached_at": "2026-02-14T10:05:00Z"
      },
      {
        "client_id": "cli_222",
        "user_email": "[email protected]",
        "mode": "observer",
        "attached_at": "2026-02-14T10:10:00Z"
      }
    ],
    "telemetry": {
      "cpu_percent": 45.2,
      "memory_percent": 62.1,
      "disk_percent": 78.5
    }
  }
}

How do I get the active session for a machine?


GET /v1/machines/:machine_id/session

Returns the active session for a machine.

Example


# Get the currently active session for a specific machine
curl "https://api.cmdop.com/v1/machines/mach_xyz789/session" \
  -H "Authorization: Bearer cmd_xxx"

Response


{
  "data": {
    "session_id": "sess_abc123",
    "status": "CONNECTED",
    "machine_hostname": "prod-server",
    "connected_at": "2026-02-14T10:00:05Z"
  }
}

Error: No Active Session


{
  "error": {
    "code": "session_not_found",
    "message": "No active session for this machine"
  }
}

What are the session status values?

Status	Description
`PENDING`	Session created, waiting for agent
`CONNECTED`	Active, bidirectional streaming
`BACKGROUND`	Mobile app backgrounded
`GRACE_PERIOD`	Agent disconnected, waiting for reconnect (30s)
`DISCONNECTED`	Final state
`ERROR`	Fatal error occurred

What lifecycle events do sessions emit?

Sessions emit events that can be received via webhooks:

Event	Description
`session.created`	New session created
`session.connected`	Agent connected
`session.client_attached`	Client attached
`session.client_detached`	Client detached
`session.grace_period`	Entered grace period
`session.disconnected`	Session ended

How do I get session command history?


GET /v1/sessions/:session_id/history

Returns command history for the session.

Example


# Fetch the last 50 commands executed in this session
curl "https://api.cmdop.com/v1/sessions/sess_abc123/history?limit=50" \
  -H "Authorization: Bearer cmd_xxx"

Response


{
  "data": [
    {
      "command_id": "cmd_111",
      "command": "ls -la",
      "exit_code": 0,
      "executed_at": "2026-02-14T10:15:00Z",
      "user_email": "[email protected]"
    },
    {
      "command_id": "cmd_222",
      "command": "cat /etc/hostname",
      "exit_code": 0,
      "executed_at": "2026-02-14T10:16:00Z",
      "user_email": "[email protected]"
    }
  ]
}

How do I get session telemetry metrics?


GET /v1/sessions/:session_id/metrics

Returns telemetry metrics.

Example


# Get real-time CPU, memory, disk, and network metrics
curl "https://api.cmdop.com/v1/sessions/sess_abc123/metrics" \
  -H "Authorization: Bearer cmd_xxx"

Response


{
  "data": {
    "session_id": "sess_abc123",
    "timestamp": "2026-02-14T10:30:00Z",
    "cpu_percent": 45.2,
    "memory_percent": 62.1,
    "disk_percent": 78.5,
    "network_rx_bytes": 1234567,
    "network_tx_bytes": 987654,
    "uptime_seconds": 123456
  }
}

What errors can the Sessions API return?

Session Not Found (404)


{
  "error": {
    "code": "session_not_found",
    "message": "Session not found",
    "details": {
      "session_id": "sess_invalid"
    }
  }
}

Session Not Active (409)


{
  "error": {
    "code": "session_not_active",
    "message": "Session is not in CONNECTED state",
    "details": {
      "current_status": "DISCONNECTED"
    }
  }
}

What should I read next?

Machines API — Machine management
Commands API — Execute commands