---
title: "Get proxy connection strings"
method: GET
path: "/v1/proxy/packages/{package_id}/connection-string"
tags: ["Packages"]
---

# Get proxy connection strings

`GET /v1/proxy/packages/{package_id}/connection-string`

## Request

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

Build ready-to-use proxy connection strings for a package, with targeting and session rules encoded for you. The returned credentials are used against the proxy gateway (`proxy.soax.com:1337`) — not against this API.

Location parameters are validated against what the package can actually target: an unavailable country, region, city, ISP, ASN, or ZIP returns 400. `region`, `city`, `isp`, `asn`, and `zip` all require `country` to be set.

Rotation and error handling: `rotate-time` and `rotate-requests` are mutually exclusive; `on-error=retry` requires `retries`, and `retries` is only valid with `on-error=retry`; `bind=node` is incompatible with `prefer=lookalike` and `on-error=replace`. When any rotation/error/bind rule is used (or `count` > 1) and no `session` is given, a session ID is generated automatically; with `count` > 1 the session IDs are numbered so each connection string gets its own IP.

For packages using IP allowlist authentication, rules are encoded in the hostname (HTTPS only), `username` is empty, and `password` is `null`.

Requires the `proxy:packages:read` scope.

## Path parameters

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

## Query parameters

- `protocol` 'https' | 'http' | 'socks5', nullable: Protocol to build the string for. Must be enabled on the package; IP-auth packages support `https` only. If omitted, the `uri` is returned without a scheme prefix.
- `count` integer: Number of connection strings to return (1–1000). Each gets a numbered session ID so it maps to a distinct IP.
- `network` 'residential' | 'mobile' | 'any', nullable: Restrict to a network type.
- `country` string, nullable: Two-letter ISO country code to target (e.g. `us`). Required when `region`, `city`, `isp`, `asn`, or `zip` is set.
- `region` string, nullable: Region to target. Use codes from the package regions endpoint. Requires `country`.
- `city` string, nullable: City to target. Use codes from the package cities endpoint. Requires `country`.
- `isp` string, nullable: ISP to target. Use codes from the package ISPs endpoint. Requires `country`.
- `asn` string, nullable: ASN to target (e.g. `AS7922`). Requires `country` and the ASN targeting feature on your plan.
- `zip` string, nullable: ZIP/postal code to target. Requires `country` and the ZIP targeting feature on your plan.
- `prefer` 'lookalike', nullable: Routing preference. `lookalike` prefers replacement nodes with similar characteristics (same region/ISP) when a node is rotated or replaced.
- `rotate-time` integer, nullable: Rotate to a new IP after this many seconds. Mutually exclusive with `rotate-requests`.
- `rotate-requests` integer, nullable: Rotate to a new IP after this many requests. Mutually exclusive with `rotate-time`.
- `on-error` 'replace' | 'fail' | 'retry', nullable: What to do when the current node fails: `replace` picks a new node (default behavior), `retry` retries the same node (`retries` required), `fail` returns the error to your client.
- `retries` integer, nullable: Number of retry attempts on the same node before replacement. Only valid with `on-error=retry`.
- `session` string, nullable: Custom session ID: lowercase letters and digits, up to 16 characters. Requests sharing a session ID keep the same IP. If omitted, a session ID is generated automatically when rotation, error handling, `bind`, or `count` > 1 requires one.
- `bind` 'node', nullable: `node` locks the session to a single node: if the node fails, requests fail instead of being moved to a new IP. Incompatible with `prefer=lookalike` and `on-error=replace`.

## Response `200`

Successful Response

- ProxyConnectionStringResponse[]
  - `uri` string, required
  - `username` string, required
  - `password` string, nullable
  - `host` string, required
  - `port` integer, required

## Other responses

- `400`: A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.
- `401`: Missing, invalid, or revoked API key.
- `403`: The API key does not carry the scope this endpoint requires.
- `404`: The resource does not exist, belongs to another organization, or is 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.

---

[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)