curl --request POST \
  --url https://api.platform.soax.com/v1/proxy/packages/{package_id}/stateful-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "checkout",
  "ruleset": {
    "country": "us",
    "region": "california"
  }
}
'

{
  "data": [
    {
      "id": "7c1e9a52-3b4d-4f6a-9e8b-2d5c0a1f6b3e",
      "proxy_id": "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e",
      "name": "checkout1",
      "status": "enabled",
      "ruleset": {
        "network_type": "wifi",
        "country": "us",
        "region": "california",
        "city": null,
        "isp": null,
        "asn": null,
        "zip": null,
        "lookalike": false,
        "rotation_trigger": "timed:300",
        "error_handling": "replace"
      },
      "exit_ip": "203.0.113.42",
      "network_type": "wifi",
      "country": "us",
      "region": "california",
      "city": "los_angeles",
      "isp": "charter_communications",
      "asn": "20001",
      "zip": null,
      "bound_since": "2026-10-27T10:15:04Z",
      "port": 1337,
      "created_at": "2026-10-27T10:15:03Z",
      "updated_at": "2026-10-27T10:15:04Z",
      "connection_string": {
        "uri": "stateful-checkout1:aB3dE5fG7h@proxy.soax.com:1337",
        "username": "stateful-checkout1",
        "password": "aB3dE5fG7h",
        "host": "proxy.soax.com",
        "port": 1337
      }
    }
  ],
  "failed": 0,
  "reason": null
}

{
  "detail": "Creating 50 session(s) would exceed limit of 1000. Current: 980."
}

{
  "detail": "Invalid API key"
}

{
  "detail": "Missing required scope: proxy:packages:write"
}

{
  "detail": "Package not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "detail": "Too Many Requests"
}

{
  "detail": "None of the 1 requested sessions could be assigned a node; no sessions were created."
}

{
  "detail": "None of the 1 requested sessions could be assigned a node; no sessions were created."
}

Stateful Sessions

Create stateful sessions

Create one or more stateful sessions on a package. Each session is bound to a matching exit node before the response returns, so you get its exit IP and connection string straight away.

The ruleset is optional: omit it or send {} to use the defaults (lookalike: false, rotation_trigger: "timed:300", error_handling: "replace"). With count > 1, each session gets the base name plus a number (job gives job1, job2, …).

Node assignment is per session. A session that cannot be bound is discarded, so the response can hold fewer sessions than you asked for: check failed and reason. If none could be bound, the request fails with 503 and a Retry-After header.

Creates for the same package run one at a time; an overlapping create may get 429.

Requires the proxy:packages:write scope.

POST

proxy

packages

{package_id}

stateful-sessions

curl --request POST \
  --url https://api.platform.soax.com/v1/proxy/packages/{package_id}/stateful-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "checkout",
  "ruleset": {
    "country": "us",
    "region": "california"
  }
}
'

{
  "data": [
    {
      "id": "7c1e9a52-3b4d-4f6a-9e8b-2d5c0a1f6b3e",
      "proxy_id": "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e",
      "name": "checkout1",
      "status": "enabled",
      "ruleset": {
        "network_type": "wifi",
        "country": "us",
        "region": "california",
        "city": null,
        "isp": null,
        "asn": null,
        "zip": null,
        "lookalike": false,
        "rotation_trigger": "timed:300",
        "error_handling": "replace"
      },
      "exit_ip": "203.0.113.42",
      "network_type": "wifi",
      "country": "us",
      "region": "california",
      "city": "los_angeles",
      "isp": "charter_communications",
      "asn": "20001",
      "zip": null,
      "bound_since": "2026-10-27T10:15:04Z",
      "port": 1337,
      "created_at": "2026-10-27T10:15:03Z",
      "updated_at": "2026-10-27T10:15:04Z",
      "connection_string": {
        "uri": "stateful-checkout1:aB3dE5fG7h@proxy.soax.com:1337",
        "username": "stateful-checkout1",
        "password": "aB3dE5fG7h",
        "host": "proxy.soax.com",
        "port": 1337
      }
    }
  ],
  "failed": 0,
  "reason": null
}

{
  "detail": "Creating 50 session(s) would exceed limit of 1000. Current: 980."
}

{
  "detail": "Invalid API key"
}

{
  "detail": "Missing required scope: proxy:packages:write"
}

{
  "detail": "Package not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "detail": "Too Many Requests"
}

{
  "detail": "None of the 1 requested sessions could be assigned a node; no sessions were created."
}

{
  "detail": "None of the 1 requested sessions could be assigned a node; no sessions were created."
}

Authorizations

Authorization

string

header

required

API key secret (starts with s_live_). Create keys in the dashboard under Settings → API keys, or via POST /v1/api-keys/. Send it as Authorization: Bearer <secret>.

Path Parameters

package_id

string

required

The ID of the proxy package (UUID format)

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Body

application/json

name

string | null

Session name, ^[a-z0-9]{1,16}$, unique within the package. With count > 1 it is the base name and each session gets a number appended, which counts toward the 16 characters. Omit it and a name is generated.

ruleset

StatefulSessionRequestRulesetSchema · object

Show child attributes

count

integer

default:1

Number of sessions to create, 1 to 1000.

Required range: 1 <= x <= 1000

Response

Successful Response

data

StatefulSessionResponse · object[]

required

Show child attributes

failed

integer

required

reason

string | null

Getting Started

Proxies

Dashboard

Trust & Safety

API Reference

Code Examples

Troubleshooting

Create stateful sessions

Authorizations

Path Parameters

Body

Response