POST /sessions
Lease a remote Chromium under one browser profile and get its one-time CDP address.
Syntax
POST https://grid-lab.zyxio.xyz/sessions
x-api-key: <key>
content-type: application/json
{"profileId": "<profile>", "ttlMinutes": <minutes>, "network": "public-web-only/v1"}Request
| Name | Where | Required | Meaning |
|---|---|---|---|
x-api-key | header | yes, or Authorization | Your API key, or Authorization: Bearer <token> from Zyxio sign-in. |
profileId | body | no | desktop-chrome-nl/v2 (default) or native-headless-chromium/v2. |
ttlMinutes | body | no | The lifetime, 1 to 240 minutes; 30 when left out. |
network | body | no | public-web-only/v1 for a browser that can reach only the public internet. Left out, the browser has the grid's ordinary network access. |
An empty body {} leases the default profile for 30 minutes. Any other field is refused.
Response
201 Created
| Field | Meaning |
|---|---|
sessionId | The session's id. |
cdpUrl | The HTTPS address to connect a CDP client to, for example with Playwright's connectOverCDP. It contains the session's access token and is returned only here, never by GET /sessions. |
expiresAt | When the session ends at the latest. |
profileId | The profile you asked for. |
attestation | null while the browser starts. Poll GET /sessions until it is filled in. |
networkPolicy | The network policy you asked for, or null. |
networkAttestation | null here; on the running session, proof that the policy is active. |
Errors
| Status | Body | When | What to do |
|---|---|---|---|
400 | {"error": "invalid session body", "detail": [...]} | An unknown profile, field or policy, or ttlMinutes outside 1 to 240. | Fix the body. |
401 | {"error": "unauthorized"} | No credential, or a key that is revoked, expired, wrong, or of a suspended account. | Send a valid key. |
503 | {"error": "accounting_unavailable"} | Your key or Zyxio sign-in could not be checked because the account database did not answer in time. Nothing was done. | Retry shortly; the same request is safe to resend. |
402 | {"error": "insufficient_credit", "requiredMicros": ..., "availableMicros": ...} | Your account is metered, credit enforcement is on, and the lease's reservation exceeds your available credit (with monthly invoicing: what your monthly limit and the unpaid-usage ceiling leave; nothing while invoicing is paused or an invoice is past due). | Top up, raise your monthly limit or pay the past-due invoice, or ask for a shorter ttlMinutes. |
402 | {"error": "daily_cap_exceeded", ...} | The key's daily cap would be exceeded. | Raise the cap, or wait for 00:00 UTC. |
403 | {"error": "forbidden"} | A valid Zyxio sign-in token whose identity has no account here, or whose account is suspended. | Accept your invitation first, or use a key. |
403 | {"error": "account_suspended"} | Credit enforcement is on and the account a Zyxio-internal credential is billed to is suspended. Nothing was started. (A suspended customer's own keys and sign-in are refused before this, with 401 and 403 forbidden.) | Ask Zyxio. |
409 | {"error": "session limit reached: ..."} | Every session slot is taken. | Try again later. |
503 | {"error": "sessions disabled"} | Sessions are switched off on the grid. | Try again later. |
Example
curl -s https://grid-lab.zyxio.xyz/sessions \
-H "x-api-key: $BROWSERGRID_API_KEY" \
-H "content-type: application/json" \
-d '{"ttlMinutes": 30}'{
"sessionId": "a1b2c3d4e5f6",
"cdpUrl": "https://grid-lab.zyxio.xyz/sessions/a1b2c3d4e5f6/<token>",
"expiresAt": "2026-10-10T12:30:00.000Z",
"profileId": "desktop-chrome-nl/v2",
"attestation": null,
"networkPolicy": null,
"networkAttestation": null
}Billing
The lease reserves its whole lifetime at €0.07 per hour: a 30-minute lease reserves 35,000 µ€ (€0.035). The meter starts when the session first becomes ready, so start-up is free, and a session that never becomes ready costs nothing. When the session ends (released, expired or lost) it is charged for its ready time, rounded once to the micro-euro, and the rest is released. A session you release with DELETE /sessions/{sessionId} settles at once; one that expires or is lost settles within one settlement interval (30 seconds).
See also
Browser sessions, GET /sessions, DELETE /sessions/{sessionId}.