REST API Cloud Sessions

Cloud session routes record the lifetime and account usage for a cloud simulator, box, or build. They do not provision that infrastructure. The service that owns the simulator, box, or build starts the metering session, heartbeats it while the resource is alive, and stops it during teardown.

These routes require the sims scope.

#Start a session

POST /api/v1/rnx/sessions
Authorization: Bearer sk_rnx_...
Content-Type: application/json

{
  "kind": "sim",
  "name": "iOS preview",
  "externalId": "provider-sim-123",
  "device": "iPhone 16 Pro",
  "tier": "semantic",
  "region": "us-west"
}

kind is required and must be sim, box, or build. size selects the simulator meter, so a service hosting a micro simulator must send size: "micro". The optional fields name, externalId, device, tier, and region let the owning service map its resource to the account record. tier accepts semantic or pixel. projectId and repoId may also associate the usage with an account resource.

An API key always starts the session on its own account. If accountId is present and names another account, the request returns 403 forbidden. A session Bearer token names a person rather than an account, so it must send an accountId the signed-in user can access.

A successful start returns 201:

{
  "session": {
    "id": "rnxbox_...",
    "accountId": "acct_...",
    "externalId": "provider-sim-123",
    "kind": "sim",
    "name": "iOS preview",
    "status": "running",
    "device": "iPhone 16 Pro",
    "tier": "semantic",
    "region": "us-west",
    "startedAt": 1788072000000,
    "stoppedAt": null,
    "stopReason": null,
    "meteredMs": 0,
    "retailMicrocents": 0,
    "projectId": null,
    "repoId": null
  }
}

Starting a session checks account coverage and the plan’s concurrency limit. It returns 402 when the account cannot cover the operation and 429 concurrency_limit when that kind is already at its limit.

#Heartbeat a session

POST /api/v1/rnx/sessions/<session-id>
Authorization: Bearer sk_rnx_...

A heartbeat banks elapsed runtime and returns the updated session. Send one at least every five minutes. A session that misses that window is stopped as idle at its last successful heartbeat, so an absent client does not keep accruing usage.

#Stop a session

DELETE /api/v1/rnx/sessions/<session-id>
Authorization: Bearer sk_rnx_...

Stopping banks the remaining runtime and returns the session with status: "stopped". An API-key stop records stopReason: "client". Stopping an already stopped session returns 200 with the same stopped session and adds no further charge.

#List sessions

GET /api/v1/rnx/sessions
Authorization: Bearer sk_rnx_...

The response contains the account’s running and stopped sessions:

{
  "sessions": []
}

API keys read their own account without a query parameter. A session Bearer token must request ?accountId=<account-id>.

Metering debits the same usage grants, prepaid balance, and spending limits described under Billing and Limits. See Remote simulator pricing for the current rates.