Sandbox pool capacity.

GET

/capacity

const url = 'https://shiftagent.example.com/capacity';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://shiftagent.example.com/capacity \
  --header 'Authorization: Bearer <token>'

Live sandbox-pool state — lets adapters pre-check before choosing an on_capacity strategy or creating sticky conversations, and observe saturation over time. Values are a point-in-time snapshot; they can change before the next request lands.

Authorizations

integrationKey

Responses

200

Current pool state.

application/json

Point-in-time sandbox pool state.

object

object

required

string

Allowed value: capacity

pool_size

required

Total sandbox slots in the deployment.

integer

warm_available

required

Warm-pool sandboxes free right now.

integer

sticky_active

required

Sandboxes currently leased to sticky conversations.

integer

at_capacity

required

True when no sandbox is available — new runs will 429 (reject) or queue (hold).

boolean

max_hold_seconds

Deployment-configured maximum time a hold request may queue before terminating capacity-exhausted.

integer

checked_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

Examples

pool

Pool with headroom

{
  "object": "capacity",
  "pool_size": 8,
  "warm_available": 3,
  "sticky_active": 2,
  "at_capacity": false,
  "max_hold_seconds": 120,
  "checked_at": "2026-07-02T10:00:00Z"
}

401

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}