---
title: "Create a dynamic or static proxy session asynchronously."
method: POST
path: "/sessions"
---

# Create a dynamic or static proxy session asynchronously.

`POST /sessions`

## Request

- Base URL: `https://api.nexalayer.net/v1`
- URL: `https://api.nexalayer.net/v1/sessions`
- Auth: API key in header `X-API-Key`

## Headers

- `Idempotency-Key` string

## Request body

- CreateSessionRequest
  - `session_type` 'dynamic' | 'static', required
  - `product_no` string, required
  - `provisioning_mode` 'purchase' | 'existing': Use existing for a resource already configured on the backend account; no NexaLayer purchase or charge is made.
  - `resource_id` string: Optional existing static order number. If omitted, NexaLayer selects a usable static resource on the account.
  - `quantity` number: Greater than 0. Dynamic sessions use GB and may be fractional. Static sessions use IP count and must be an integer.
  - `duration` integer
  - `protocol` 'socks5' | 'http' | 'https'
  - `country_code` string
  - `city_code` string
  - `project_id` string: Static shared proxy project code. Required by some shared static products.
  - `rotation_mode` 'fixed' | 'timed' | 'on_demand'
  - `rotation_interval_sec` integer

## Response `202`

Session creation accepted. Poll GET /sessions/{session_id}. POST /sessions does not accept include_credentials; this response has no proxy credentials because the session is still being created.

- SessionResponse
  - `success` boolean
  - `data` object
    - `session_id` string
    - `session_type` string
    - `status` string
    - `provisioning_mode` 'purchase' | 'existing'
    - `proxy` object
      - `host` string
      - `port` integer
      - `username` string: Omitted unless the request set include_credentials=true. Present on GET session detail and rotate only when that query flag is true, and on renew responses for an active session.
      - `password` string: Omitted unless the request set include_credentials=true. Present on GET session detail and rotate only when that query flag is true, and on renew responses for an active session.
      - `protocol` string
      - `full_url` string, nullable: Omitted unless the request set include_credentials=true. Present on GET session detail and rotate only when that query flag is true, and on renew responses for an active session. Do not log this value.
    - `health` object
      - `risk_level` 'low' | 'medium' | 'high'
      - `health_score` integer
      - `success_rate` number
      - `consecutive_failures` integer

## Other responses

- `402`: HTTP 402. INSUFFICIENT_BALANCE means the account balance cannot cover the charge. BUDGET_EXCEEDED means a key or daily spend limit, or a paused key, blocked the charge. See https://docs.nexalayer.net/en/errors.
- `409`: HTTP 409. PRICE_MISMATCH means the price changed since it was read; no order was placed, so re-read prices and retry. Also used for PRODUCT_OUT_OF_STOCK and IDEMPOTENCY_CONFLICT. See https://docs.nexalayer.net/en/errors.
- `422`: The request is valid but cannot be fulfilled in the current product or budget state.
- `429`: Request or trial limit exceeded.

---

[API](https://skmtc.dev/nexalayer/apis/nexalayer-agent-api.md) · [All operations](https://skmtc.dev/nexalayer/apis/nexalayer-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexalayer/apis/nexalayer-agent-api/revisions/126d0d474804?raw)