API Reference

REST API endpoints for quota management, usage tracking, and session history

Authentication

All API endpoints require Bearer token authentication

Authorization: Bearer your-user-token-here
GET/api/quota

GET /api/quota

Check remaining quota before launching jobs

Response: Returns total, used, remaining quota and percentage used

Example Request:

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/quota

Example Response:

{
  "remainingQuota": 7650,
  "pricing": {
    "baseRate": 1,
    "multiplier": 1.0,
    "effectiveRate": 1.0,
    "breakdown": {
      "base": 1.0,
      "maxSessions": 1,
      "sessionMultiplier": 1.0,
      "userDataMax": 5,
      "userDataPremium": 0,
      "hasLiveURLAccess": false,
      "liveURLPremium": 0
    }
  }
}
GET/api/usage

GET /api/usage

Get usage statistics for reporting and cost analysis

Response: Returns total sessions, total minutes, and active sessions count

Example Request:

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/usage

Example Response:

{
  "totalSessions": 142,
  "totalMinutes": 2350,
  "activeSessions": 1
}
GET/api/history

GET /api/history

Retrieve session history for audit trails

Optional start and end query parameters (ISO 8601 timestamps)

Response: Returns array of session objects with duration and disconnect reasons

Example Request:

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/history

Example Response:

{
  "sessions": [
    {
      "id": 1,
      "startedAt": "2025-01-15T10:30:00Z",
      "endedAt": "2025-01-15T10:33:25Z",
      "durationMinutes": 3,
      "quotaConsumed": 3,
      "disconnectReason": "client_closed"
    }
  ],
  "total": 1
}
POST/api/user-data

POST /api/user-data

Create a new User Data container for persistent browser state (cookies, localStorage, etc.)

Response: Returns the created User Data ID and timestamp

Example Request:

curl -X POST -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

Example Response:

{
  "id": "udd_abc123xyz789defg",
  "createdAt": "2025-01-15T10:30:00Z"
}
GET/api/user-data

GET /api/user-data

List all User Data containers for the authenticated user

Response: Returns array of User Data objects with quota information

Example Request:

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

Example Response:

{
  "items": [
    {
      "id": "udd_abc123xyz789defg",
      "createdAt": "2025-01-15T10:30:00Z",
      "lastUsedAt": "2025-01-15T12:45:00Z",
      "isLocked": false
    }
  ],
  "total": 1,
  "quota": {
    "used": 1,
    "max": 5,
    "canCreate": true
  }
}
DELETE/api/user-data/:id

DELETE /api/user-data/:id

Delete a User Data container and release quota

Response: Returns success status

Example Request:

curl -X DELETE -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data/udd_abc123xyz789defg

Example Response:

{
  "success": true
}

Billing Model

Usage-based billing: 1 minute of browser session time = 1 quota unit

Disconnect Reasons

client_closed— Client called browser.close()
client_disconnected— WebSocket connection closed unexpectedly
server_closed— Browser server closed the connection
insufficient_balance— Quota exhausted during session
socket_timeout— No data transferred for 5 minutes
tcp_error— Network error