Skip to content

API Reference / Proxy sessions

Create many proxy sessions

Adds many proxy sessions to one imported (provider-less) pool in a single transaction, typically when seeding a pool. The operation is idempotent on the pool and session token, so re-running it does not create duplicates.

POST/proxies.v1.Proxies/BulkCreateSessions

Request body

application/jsonRequired

Request to add or update many endpoints in one imported pool in one step, up to 10000. Keyed by token, so repeating a request changes nothing further.

poolId?string

Opaque 16-byte identifier of the imported pool for every session, base64-encoded in JSON. A provider's pool is rejected.

Format"byte" base64

sessions?array<CreateSessionInput>

The sessions to add or update, at most 10000. More is rejected with invalid_argument. When a token repeats, the last entry wins.

Show attributes
host?string

Endpoint host name or IP address.

password?string

Password for proxy authentication. Write only: stored encrypted and never returned. Empty for an endpoint that authenticates by IP address.

port?integer

Endpoint TCP port, from 1 to 65535.

Format"int32"

scheme?string

Protocol used to connect: "http", "https" or "socks5". Absent or empty means "http".

token?string

A key of your choosing for the session, unique within the pool. Sending the same token again updates that session rather than adding another.

username?string

Username for proxy authentication. Absent for none.

Response body

application/json

Success

sessions?array<ProxiesSession>

The sessions for the request's tokens, without passwords.

Show attributes
addressRange?string

Address range the endpoint's address belongs to, in CIDR notation, as the provider reports it or as the address's /24 when it does not. Absent when not known.

assignedAccountNames?array<string>

Steam account names currently assigned to the session, in name order. Empty when no account uses it, and in create and update responses.

carrier?string

Network the endpoint's address comes from, as an ASN such as AS8881, when the provider reports it or it was bought on a named network. Absent when not known.

country?string

Exit country of the endpoint as an upper-case ISO 3166-1 alpha-2 code, as reported by the provider. Absent when the country is not known, such as for an imported endpoint or a rotating provider's slot.

createdAt?string

When the session was created.

Format"date-time"

deletedAt?string

When the session was deleted. Absent while it is live.

Format"date-time"

enabled?boolean

True when the session can be handed to accounts. Disabling it moves its unpinned accounts to other sessions.

health?ProxiesSessionHealth

The session's latest health check result. Absent when it has never been checked, and in create and update responses.

Show attributes
condition?string

Why the session counts as failing although its checks pass, such as long-lived connections through it being cut again and again. Unspecified when nothing beyond the checks is wrong. While set, every check counts as failed, so the session leaves placement and, where replacement is switched on, is replaced.

Value in"SESSION_HEALTH_CONDITION_CONNECTIONS_CUT"

conditionObservedAt?string

When the condition was last seen. The session keeps the condition for 24 hours after this, so moving its accounts away does not bring it straight back. Absent when there is no condition.

Format"date-time"

consecutiveFailures?integer

Number of checks in a row that have failed. Reset to zero by a successful check.

Format"int32"

exitAddress?string

The address the proxy's traffic leaves from, as last observed: a fixed endpoint's own address, or for a rotating proxy the address our echo saw. Absent until it has been observed.

exitCity?string

City the exit address is in, in English, from a location database lookup. Approximate, and absent when the exit address is not known or the database has no city for it.

exitCountry?string

Country the exit address is in, as an upper-case ISO 3166-1 alpha-2 code, from a location database lookup. Absent when the exit address is not known or the database has no country for it.

exitSeenAt?string

When the exit address was last observed. Absent until it has been.

Format"date-time"

healthy?boolean

True once a health check has confirmed the session works and it has not since failed too many checks in a row.

lastFailureAt?string

When a check last failed. Absent when none has.

Format"date-time"

lastFailureClass?string

The kind of error of the last failed check, such as authentication failed or connection timeout. Unspecified until a check fails.

Value in"REQUEST_ERROR_CLASS_DIAL_TIMEOUT""REQUEST_ERROR_CLASS_DIAL_REFUSED""REQUEST_ERROR_CLASS_AUTH_FAILED""REQUEST_ERROR_CLASS_TLS_HANDSHAKE""REQUEST_ERROR_CLASS_ROUNDTRIP_TIMEOUT""REQUEST_ERROR_CLASS_UPSTREAM_5XX""REQUEST_ERROR_CLASS_UPSTREAM_429""REQUEST_ERROR_CLASS_BODY_READ""REQUEST_ERROR_CLASS_CLIENT_CANCELLED"

lastFailureStatusCode?integer

HTTP status of the last failed check, such as 407 for rejected credentials. Zero until a check fails, and kept after later successes.

Format"int32"

lastSuccessAt?string

When a check last succeeded. Absent when none has.

Format"date-time"

latency?string

Round trip time of the last successful check, in milliseconds. Absent until a check succeeds.

probedAt?string

When the session was last checked, whether the check passed or failed.

Format"date-time"

reconnectCount?integer

For the connections cut condition: the most times one account opened its connection through the session in the 30 minutes before the condition was last seen. Zero when there is no condition.

Format"int32"

sessionId?string

Opaque 16-byte identifier of the session checked, base64-encoded in JSON.

Format"byte" base64

workspaceId?string

Opaque 16-byte identifier of the workspace that owns the session, base64-encoded in JSON.

Format"byte" base64

host?string

Endpoint host name or IP address of a fixed endpoint. Empty for a rotating provider's slot.

id?string

Opaque 16-byte identifier of the session, assigned on creation. Base64-encoded in JSON.

Format"byte" base64

poolId?string

Opaque 16-byte identifier of the pool the session belongs to, base64-encoded in JSON.

Format"byte" base64

port?integer

Endpoint TCP port of a fixed endpoint, from 1 to 65535. Zero for a rotating provider's slot.

Format"int32"

providerId?string

Opaque 16-byte identifier of the provider the session comes from, base64-encoded in JSON. Empty for a session in an imported pool.

Format"byte" base64

scheme?string

Protocol used to connect: "http", "https" or "socks5".

slot?integer

Slot number of a Webshare residential session, the token as an integer. Absent for other sessions.

Format"int32"

token?string

The session's key within its pool: the sticky session identifier for a rotating provider, or the endpoint key for a fixed endpoint. Unique within the pool and never changes.

updatedAt?string

When the session was last changed.

Format"date-time"

username?string

Username for proxy authentication of a fixed endpoint. Empty for a rotating provider's slot or an endpoint that authenticates by IP address.

version?string

Edit counter, incremented by every change a user makes to the session.

Format"int64"

workspaceId?string

Opaque 16-byte identifier of the workspace that owns the session, base64-encoded in JSON.

Format"byte" base64

curl -X POST "https://api.goldmine.to/proxies.v1.Proxies/BulkCreateSessions" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "poolId": "AY+MJGZmfd2O7jo6Ojo6Og==",
    "sessions": [
      {
        "token": "sess-1",
        "scheme": "http",
        "host": "203.0.113.10",
        "port": 8080,
        "username": "u1",
        "password": "p1"
      },
      {
        "token": "sess-2",
        "scheme": "socks5",
        "host": "203.0.113.11",
        "port": 1080,
        "username": "u2",
        "password": "p2"
      }
    ]
  }'
{
  "sessions": [
    {
      "id": "AY+MJSIie7uMzExMTExMTA==",
      "workspaceId": "AY+MHnorfD2eTxorPE1ebw==",
      "poolId": "AY+MJGZmfd2O7jo6Ojo6Og==",
      "token": "sess-1",
      "scheme": "http",
      "host": "203.0.113.10",
      "port": 8080,
      "username": "u1",
      "enabled": true,
      "version": "1",
      "createdAt": "2026-06-29T10:15:00Z",
      "updatedAt": "2026-06-29T10:15:00Z"
    },
    {
      "id": "AY+MJTMzfMyN3UxMTExMTA==",
      "workspaceId": "AY+MHnorfD2eTxorPE1ebw==",
      "poolId": "AY+MJGZmfd2O7jo6Ojo6Og==",
      "token": "sess-2",
      "scheme": "socks5",
      "host": "203.0.113.11",
      "port": 1080,
      "username": "u2",
      "enabled": true,
      "version": "1",
      "createdAt": "2026-06-29T10:15:00Z",
      "updatedAt": "2026-06-29T10:15:00Z"
    }
  ]
}