---
title: "Update a stateful session"
method: PATCH
path: "/v1/proxy/packages/{package_id}/stateful-sessions/{session_id}"
tags: ["Stateful Sessions"]
---

# Update a stateful session

`PATCH /v1/proxy/packages/{package_id}/stateful-sessions/{session_id}`

## Request

- Base URL: `https://api.platform.soax.com`
- URL: `https://api.platform.soax.com/v1/proxy/packages/{package_id}/stateful-sessions/{session_id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/soax/apis/soax-api/docs/v1/proxy/packages/:package_id/stateful-sessions/:session_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Change a session's name, status or rules. Your client keeps the same connection string; the next request picks up the change. Renaming is the exception: the username is `stateful-<name>`, so a rename changes it.

Send only what you want to change. In `ruleset`, an omitted field keeps its stored value and an explicit `null` clears a geo field or `network_type`. `lookalike`, `rotation_trigger` and `error_handling` cannot be `null`.

Changing a geo field to a different value clears the fields beneath it that you did not send: changing `country` clears `region`, `city`, `isp`, `asn` and `zip`; changing `region` clears `city`, `isp`, `asn` and `zip`; changing `city` clears `isp`, `asn` and `zip`. `isp`, `asn` and `zip` never clear one another.

Set `status` to `disabled` to stop a session carrying traffic without losing its name, port or rules, and back to `enabled` to resume. Re-enabling binds a new node; if none is available the call returns `502` and the session stays disabled.

Requires the `proxy:packages:write` scope.

## Path parameters

- `package_id` string, required: The ID of the proxy package (UUID format)
- `session_id` string, required: The ID of the stateful session (UUID format)

## Request body

- StatefulSessionUpdateRequest
  - `name` string, nullable: New name, `^[a-z0-9]{1,16}$`. Changes the connection string username.
  - `ruleset` StatefulSessionRequestRulesetSchema
    - `network_type` 'wifi' | 'mobile' | 'any', nullable: `wifi` (residential), `mobile`, or `any`. Must be enabled on the package.
    - `country` string, nullable: Two-letter country code, or `any`. Must be available on the package. Required when any of `region`, `city`, `isp`, `asn` or `zip` is set.
    - `region` string, nullable: Region code from the package location endpoints. Must belong to `country`.
    - `city` string, nullable: City code from the package location endpoints. Must belong to `region`, or to `country` when no region is set.
    - `isp` string, nullable: ISP code from the package location endpoints, valid for the chosen country, region and city.
    - `asn` string, nullable: ASN from the package location endpoints. Requires ASN targeting on your plan.
    - `zip` string, nullable: ZIP code from the package location endpoints. Requires ZIP targeting on your plan.
    - `lookalike` boolean, nullable: `true` or `false`: whether a replacement node should resemble the previous one (same ISP and location where possible). Defaults to `false` on create. Cannot be `true` with `rotation_trigger: "bind"`. On update, omit it to keep the stored value; `null` is rejected (422).
    - `rotation_trigger` string, nullable: When the exit node changes: `timed:<seconds>` (minimum 10), `request-count:<requests>`, `on-error` (only when the node fails) or `bind` (pin the node). Defaults to `timed:300` on create. `bind` cannot be combined with `error_handling: "replace"` or `lookalike: true`. On update, omit it to keep the stored value; `null` is rejected (422).
    - `error_handling` string, nullable: What happens when the bound node fails: `replace` (switch to a new node), `retry_<attempts>` (retry on the same node first) or `fail` (return the error). Defaults to `replace` on create, or `retry_3` when `rotation_trigger` is `bind`. On update, omit it to keep the stored value; `null` is rejected (422).
  - `status` 'enabled' | 'disabled'

## Response `200`

Successful Response

- StatefulSessionResponse
  - `id` string, required
  - `proxy_id` string, required
  - `name` string, required
  - `status` 'enabled' | 'disabled', required
  - `ruleset` StatefulSessionRulesetSchema, required
    - `network_type` 'wifi' | 'mobile' | 'any', nullable: `wifi` (residential), `mobile`, or `any`. Must be enabled on the package.
    - `country` string, nullable: Two-letter country code, or `any`. Must be available on the package. Required when any of `region`, `city`, `isp`, `asn` or `zip` is set.
    - `region` string, nullable: Region code from the package location endpoints. Must belong to `country`.
    - `city` string, nullable: City code from the package location endpoints. Must belong to `region`, or to `country` when no region is set.
    - `isp` string, nullable: ISP code from the package location endpoints, valid for the chosen country, region and city.
    - `asn` string, nullable: ASN from the package location endpoints. Requires ASN targeting on your plan.
    - `zip` string, nullable: ZIP code from the package location endpoints. Requires ZIP targeting on your plan.
    - `lookalike` boolean, nullable: Whether a replacement node should resemble the previous one.
    - `rotation_trigger` string, nullable: `bind`, `on-error`, `timed:<seconds>` (minimum 10) or `request-count:<requests>`.
    - `error_handling` string, nullable: `replace`, `fail` or `retry_<attempts>`.
  - `exit_ip` string, required: IP address of the exit node the session is bound to now.
  - `network_type` string, required: Network of the bound node. The top-level geo and network fields describe where the session is bound now; `ruleset` holds what you asked for.
  - `country` string, required
  - `region` string, nullable
  - `city` string, nullable
  - `isp` string, nullable
  - `asn` string, nullable
  - `zip` string, nullable
  - `bound_since` string, date-time, nullable: When the session was bound to its current node.
  - `port` integer, nullable: Gateway port to connect to. IP allowlist packages get a dedicated port per session; credential packages share the gateway port.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `connection_string` ConnectionStringSchema
    - `uri` string, required
    - `username` string, required
    - `password` string, nullable
    - `host` string, required
    - `port` integer, required

## Other responses

- `400`: Invalid name or ruleset.
- `401`: Missing, invalid, or revoked API key.
- `403`: The API key does not carry the scope this endpoint requires.
- `404`: Session not found, or outside the API key's package restriction.
- `422`: Validation Error
- `429`: Rate limit exceeded (5 requests/second per API key, 500 requests/minute per IP). The response includes `Retry-After` (seconds), `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (Unix time) headers — wait `Retry-After` seconds and retry.
- `502`: Re-enabling failed because no node could be assigned. The session stays disabled.

---

[API](https://skmtc.dev/soax/apis/soax-api.md) - [All operations](https://skmtc.dev/soax/apis/soax-api/llms.txt) - [OpenAPI document](https://skmtc.dev/soax/apis/soax-api/revisions/2abdaa934277?raw)