Hivebrowser
API Reference

Usage & Settings

Usage metrics, runner status, and team settings.

Use forOperational visibility

Track usage, runner health, and team runtime settings.

DiagnoseSeparate capacity from code failures

Compare failed sessions against runner availability, quota, and team limits.

ControlKeep changes intentional

Treat settings and runner status changes as owned admin actions.

Operational Boundary

Usage endpoints show runtime consumption, runner endpoints help separate capacity issues from code failures, and team settings expose limits and defaults that affect new sessions. Treat runner status and team setting updates as administrative actions with clear ownership and auditability.

Get Usage Summary

GET/v1/usageShow endpoint detailsHide endpoint details
GET/v1/usage

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

cURL
curl -X GET "https://api.hivebrowser.ai/v1/usage" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/usage", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Usage summary

Response example
{
  "data": {
    "totals": {
      "property1": 0,
      "property2": 0
    },
    "recentEvents": {
      "items": [
        {
          "id": "string",
          "teamId": "string",
          "sessionId": "string",
          "profileId": "string",
          "artifactId": "string",
          "type": "string",
          "quantity": "string",
          "unit": "string",
          "metadata": {},
          "occurredAt": "2019-08-24T14:15:22Z",
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ],
      "total": 0,
      "page": 1,
      "pageSize": 0
    }
  }
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}

List Runners

GET/v1/runnersShow endpoint detailsHide endpoint details
GET/v1/runners

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

cURL
curl -X GET "https://api.hivebrowser.ai/v1/runners" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/runners", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Runner list

Response example
{
  "data": {
    "items": [
      {
        "id": "string",
        "region": "string",
        "hostname": "string",
        "status": "ONLINE",
        "apiBaseUrl": "string",
        "connectBaseUrl": "string",
        "liveBaseUrl": "string",
        "maxSessionCount": 0,
        "currentSessionCount": 0,
        "labels": {},
        "lastHeartbeatAt": "2019-08-24T14:15:22Z",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "total": 0,
    "page": 1,
    "pageSize": 0
  }
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}

Update Runner Status

POST/v1/runners/{id}/statusShow endpoint detailsHide endpoint details
POST/v1/runners/{id}/status

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Request Body

application/jsonRequired
statusRequiredstring

New runner status

Value in: "ONLINE" | "DRAINING"

Path Parameters

idRequiredstring

Runner ID

cURL
curl -X POST "https://api.hivebrowser.ai/v1/runners/string/status" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{    "status": "ONLINE"  }'
JavaScript
fetch("https://api.hivebrowser.ai/v1/runners/string/status", {  headers: {    "Authorization": "Bearer <token>"  },  body: JSON.stringify({    "status": "ONLINE"  })});
Response 200

Runner status updated

Response example
{
  "data": {
    "id": "string",
    "region": "string",
    "hostname": "string",
    "status": "ONLINE",
    "apiBaseUrl": "string",
    "connectBaseUrl": "string",
    "liveBaseUrl": "string",
    "maxSessionCount": 0,
    "currentSessionCount": 0,
    "labels": {},
    "lastHeartbeatAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Response 400

Invalid request payload

Response example
{
  "error": "string",
  "message": "string"
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}
Response 404

Resource not found

Response example
{
  "error": "string",
  "message": "string"
}

Get Team Settings

GET/v1/team/settingsShow endpoint detailsHide endpoint details
GET/v1/team/settings

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

cURL
curl -X GET "https://api.hivebrowser.ai/v1/team/settings" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/team/settings", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Team settings

Response example
{
  "data": {
    "id": "string",
    "name": "string",
    "slug": "string",
    "planCode": "string",
    "sessionConcurrencyLimit": 1,
    "sessionMaxDurationSec": 1,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}

Update Team Settings

POST/v1/team/settingsShow endpoint detailsHide endpoint details
POST/v1/team/settings

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Request Body

application/jsonRequired
namestring

Team display name

Minimum length: 1Maximum length: 120
sessionConcurrencyLimitinteger

Maximum concurrent sessions

Minimum: 1Maximum: 100
sessionMaxDurationSecinteger

Maximum session duration in seconds (max 24 hours)

Minimum: 1Maximum: 86400
cURL
curl -X POST "https://api.hivebrowser.ai/v1/team/settings" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "sessionConcurrencyLimit": 1,    "sessionMaxDurationSec": 1  }'
JavaScript
fetch("https://api.hivebrowser.ai/v1/team/settings", {  headers: {    "Authorization": "Bearer <token>"  },  body: JSON.stringify({    "name": "string",    "sessionConcurrencyLimit": 1,    "sessionMaxDurationSec": 1  })});
Response 200

Team settings updated

Response example
{
  "data": {
    "id": "string",
    "name": "string",
    "slug": "string",
    "planCode": "string",
    "sessionConcurrencyLimit": 1,
    "sessionMaxDurationSec": 1,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Response 400

Invalid request payload

Response example
{
  "error": "string",
  "message": "string"
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}

On this page

Operational BoundaryGet Usage SummaryList RunnersUpdate Runner StatusGet Team SettingsUpdate Team Settings