Plans and features

Every Boxline organization is on a plan, and every project in it runs on that plan. The plan sets two things: limits, such as how many sessions can run at once, and feature switches, such as whether the platform’s residential proxies are included.

This page lists both, explains the error you get when a feature is not in your plan, and shows how to check your plan from code. Prices are on the pricing page. How an organization’s projects share its plan is on Organizations, projects and team members.

Limits

Your plan’s limits are in GET /v1/auth/me as project.limits. For the caps below, null means no limit. Every refusal of your plan answers with status 402: feature_not_in_plan, spend_limit or plan_limit.

These are the plan’s limits, and only we change them. You can also set your own monthly spending limit for the organization and for each project. It covers all usage and uses the same code, 402 spend_limit. See Credit and spending limits.

The plan is the organization’s, so some limits are shared. Running sessions, model spend, proxy data, CAPTCHA solves and web searches are added up over all the organization’s projects: a second project does not give you a second allowance. The refusal says “this organization”. The counts a project keeps (credentials, browser profiles, extensions, webhook endpoints, tasks and schedules) stay per project. A project can also have a lower cap on its own running sessions, concurrencyCap.

limits also has the plan’s name, its monthly priceUsd (null for custom pricing) and includedUsd, the usage included each month. For the session limits of each plan, see Sessions.

Features

A feature is a switch: your plan includes it or it does not. The API uses the names in the first column. GET /v1/pricing returns the same labels.

By default, seven features are for paid plans only: the platform’s residential and datacenter proxies, browser mode, automatic CAPTCHA solving, Chrome extensions, password credentials (website passwords with 2FA), and Boxline's own model keys (Free runs AI on your own keys). Free has every other feature. Hobby, Startup and Scale have all of them.

Your own proxy works on every plan, Free included. See Your own proxy.

When a feature is not in your plan

A call that needs a feature your plan does not include fails with 402 feature_not_in_plan. The message names the plan and the feature.

curl -X POST https://api.boxline.dev/v1/sessions \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"browser": true, "proxy": {"type": "residential", "country": "US"}}'

{  "error": {    "code": "feature_not_in_plan",    "message": "the Free plan does not include residential proxies"  }}

• The call fails before anything starts, so nothing is billed.
• It is checked each time you make a call. A change with Update a session (PATCH /v1/sessions/:id) is checked against your plan at that moment.
• Automatic CAPTCHA solving is checked again at every attempt. If your plan no longer includes it, a person is asked instead.
• Retrying does not help. The call works once your plan includes the feature, or without the option that needs it.

In the SDKs it is a BoxlineError with status 402 and code feature_not_in_plan:

import { Boxline, BoxlineError } from "@boxline/sdk";const client = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLtry {  const session = await client.sessions.create({ browser: true, proxy: { type: "residential", country: "US" } });  await session.stop();} catch (err) {  if (err instanceof BoxlineError && err.code === "feature_not_in_plan") {    console.error(err.message); // "the Free plan does not include residential proxies"  } else {    throw err;  }}

from boxline import Boxline, BoxlineErrorbx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLtry:    session = bx.sessions.create(proxy={"type": "residential", "country": "US"})    session.stop()except BoxlineError as err:    if err.code != "feature_not_in_plan":        raise    print(err.message)  # "the Free plan does not include residential proxies"

Check your plan from code

GET/v1/auth/me returns your project with its plan’s limits, and limits.features has every feature as true or false. organization has the organization’s own summary (with an API key, its role is null: a key is not a member):

"organization": {  "id": "…",  "name": "…",  "plan": "free",  "personal": true,  "suspended": null,  "role": null},"project": {  "id": "…",  "name": "…",  "plan": "free",  "orgId": "…",  "concurrencyCap": null,  "suspended": null,  "limits": {    "name": "Free",    "concurrency": …,    "maxTimeoutSeconds": …,    "captchaSolvesPerMonth": 0,    "features": {      "shell": true,      "residentialProxy": false,      "customProxy": true,      "captchaSolving": false,      …    }  },  "trajectories": { "enabled": true, "noticeSeenAt": null, "decidedBy": null }}

In TypeScript, client.hasFeature(name) answers for one feature. It calls GET /v1/auth/me each time, so when you check several, call client.me() once. The Python SDK has bx.me(), and no has_feature.

curl https://api.boxline.dev/v1/auth/me \  -H "x-api-key: $BOXLINE_API_KEY"

import { Boxline } from "@boxline/sdk";const client = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URL// One feature:if (await client.hasFeature("residentialProxy")) {  // ...}// Several: read them once.const { features } = (await client.me()).project.limits;const session = await client.sessions.create({  browser: true,  // Your own proxy works on every plan; process.env.MY_PROXY is your own setting.  proxy: features.residentialProxy    ? { type: "residential", country: "US" }    : { type: "custom", server: process.env.MY_PROXY! },  captcha: features.captchaSolving ? "solve" : "ask",});

import osfrom boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLfeatures = bx.me()["project"]["limits"]["features"]session = bx.sessions.create(    # Your own proxy works on every plan; MY_PROXY is your own setting.    proxy={"type": "residential", "country": "US"} if features["residentialProxy"]    else {"type": "custom", "server": os.environ["MY_PROXY"]},    captcha="solve" if features["captchaSolving"] else "ask",)

Check your plan when your program starts, not before every call. A call without the feature fails safely with feature_not_in_plan anyway.

Public plans

GET/v1/pricing is the public price table. It needs no API key. Besides the prices, it has:

# Which features does each public plan include?curl -s https://api.boxline.dev/v1/pricing \  | jq '.plans[] | {id, name, features: (.features | with_entries(select(.value)) | keys)}'

Prices, limits and allowances may change during the beta. Read them from this endpoint rather than copying numbers into your code.

Suspended organizations and projects

We may suspend an organization, for example for a breach of the acceptable-use rules in the Terms of Service. A suspension belongs to the organization, so it suspends every project in it. When that happens:

• The running sessions of its projects are stopped (stopReason: "suspended").
• API calls with a key of one of its projects, or a console login in it, get 403 project_suspended, with the reason in the message.
• Only a few calls still work, so you can see why: GET /v1/auth/me, signing out, changing your password, and switching to another organization. project.suspended and organization.suspended are { at, reason } (null when not suspended).
• The organization’s own pages in the console (members, projects) answer 403 organization_suspended, except reading it and leaving it.

{  "error": {    "code": "project_suspended",    "message": "this project's organization is suspended: <reason>. Contact support."  }}

Stop retrying when you get project_suspended: every call fails until the suspension is lifted. Contact support to resolve it.

try {  await client.sessions.create({ browser: true });} catch (err) {  if (err instanceof BoxlineError && err.code === "project_suspended") {    const { suspended } = (await client.me()).project;    console.error(`Suspended since ${suspended?.at}: ${suspended?.reason ?? "no reason given"}`);    process.exit(1); // do not retry  }  throw err;}

import systry:    bx.sessions.create()except BoxlineError as err:    if err.code == "project_suspended":        suspended = bx.me()["project"]["suspended"]        sys.exit(f"Suspended since {suspended['at']}: {suspended['reason'] or 'no reason given'}")    raise