Log inStart free
Core conceptsBeta

Session control

Find sessions with filters, change keep-alive and metadata, add time, and pause or release many at once.

Everything you need to run many sessions at once: find them quickly, change them while they run, and act on a whole group with one call.

Find sessions

GET/v1/sessions

QueryMeaning
statusOne or more of RUNNING, PAUSED, COMPLETED, ERROR, comma-separated.
kindbrowser (no shell), combined (browser and shell) or shell.
qThe start of a session ID, or text inside userMetadata.
from, toISO dates, compared with createdAt.
sortcreated_desc (default), created_asc or duration_desc.
limit, offsetPaging. The response includes total.
Shell
curl "https://api.staging.boxline.dev/v1/sessions?status=RUNNING,PAUSED&q=customer-42&limit=25" \
  -H "x-api-key: $BOXLINE_API_KEY"

Change a running session

PATCH/v1/sessions/:id takes keepAlive and userMetadata. POST/v1/sessions/:id/extend adds seconds (60 to 3600) to the session’s time. The total can never exceed your plan’s longest session; past that you get 403 plan_limit.

TypeScript
const client = new Boxline();
const session = await client.sessions.get(id);

await session.update({ keepAlive: true, userMetadata: { customer: "customer-42" } });
await session.extend(600); // ten more minutes

Act on many sessions

POST/v1/sessions/bulk with { action, ids } pauses, resumes or releases up to 100 sessions. Each ID gets its own result, so one failure never blocks the rest.

TypeScript
const running = await client.sessions.list({ status: "RUNNING", q: "nightly-crawl" });
const { results } = await client.sessions.bulk("release", running.map((s) => s.id));
console.log(results.filter((r) => !r.ok));

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.