Skip to content

API Reference / Proxy sessions

List proxy sessions

Returns the proxy sessions in your workspace, fully hydrated with their endpoint details, latest health verdict and assigned account names, optionally filtered by pool, enabled state, health, exit country, whether an account is assigned, or a text query over host, slot and account names. Results are paginated. Pass an empty cursor for the first page and follow the returned cursor for subsequent pages.

POST/proxies.v1.Proxies/ListSessions

Request body

application/jsonRequired

Request for one page of the proxy sessions in the caller's workspace, with optional filtering and ordering.

cursor?string

Opaque pagination cursor from a previous ListSessionsResponse. Empty for the first page.

descending?boolean

Order descending instead of ascending.

filter?SessionFilter

Optional filters applied before pagination.

Show attributes
assigned?boolean

True selects only sessions with at least one live account assignment, false only sessions with none. Unset includes both.

cities?array<string>

Exit cities to include, as the English city names the sessions report in health.exit_city, OR within the field. The empty string selects sessions whose city is not known. Empty includes sessions in every city.

countries?array<string>

Exit countries to include, as upper-case ISO 3166-1 alpha-2 codes, OR within the field. A session's country is health.exit_country when observed, otherwise the provider's country. Empty includes sessions in every country and sessions whose country is not known.

enabled?boolean

True selects only enabled sessions, false only disabled sessions. Unset includes sessions regardless of enabled state.

healths?array<string>

Health states to include. Empty includes sessions in every state.

Value in"SESSION_HEALTH_STATE_HEALTHY""SESSION_HEALTH_STATE_UNHEALTHY""SESSION_HEALTH_STATE_UNPROBED"

poolId?string

Optional pool id to limit results to a single pool. Unset includes sessions across all pools.

Format"byte" base64

query?string

Literal case-insensitive substring of the session's host, slot number or an assigned account name. Absent or empty matches every session.

limit?integer

Maximum number of sessions to return. Server caps this at a service-defined upper bound.

Format"int32"

sortField?string

Field to order the page by. Unspecified orders by creation time.

Value in"SESSION_SORT_FIELD_CREATED_AT""SESSION_SORT_FIELD_HEALTH"

Response body

application/json

Success

nextCursor?string

Cursor to pass to fetch the next page. Empty when there are no more results.

sessions?array<ProxiesSession>

Full sessions for this page, ordered by the requested sort. A page carries the hydrated entities, not bare ids, so the caller needs no follow-up GetSession.

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/ListSessions" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "filter": {
      "poolId": "AY+MISIifMyN3T09PT09PQ=="
    }
  }'
{
  "sessions": [
    {
      "id": "AY+MIjMzfu6P/05OTk5OTg==",
      "workspaceId": "AY+MHnorfD2eTxorPE1ebw==",
      "poolId": "AY+MISIifMyN3T09PT09PQ==",
      "providerId": "AY+MIBEReqqLuywsLCwsLA==",
      "token": "sess-abc123",
      "scheme": "http",
      "host": "203.0.113.10",
      "port": 8080,
      "username": "user-018f",
      "enabled": true,
      "version": "2",
      "createdAt": "2026-06-20T12:00:00Z",
      "updatedAt": "2026-06-29T09:00:00Z",
      "health": {
        "sessionId": "AY+MIjMzfu6P/05OTk5OTg==",
        "workspaceId": "AY+MHnorfD2eTxorPE1ebw==",
        "healthy": true,
        "latencyMs": 42,
        "consecutiveFailures": 0,
        "lastSuccessAt": "2026-06-29T09:05:00Z",
        "probedAt": "2026-06-29T09:05:00Z"
      }
    },
    {
      "id": "AY+MJTQ0NDQ0NDQ0NDQ0NA==",
      "workspaceId": "AY+MHnorfD2eTxorPE1ebw==",
      "poolId": "AY+MISIifMyN3T09PT09PQ==",
      "providerId": "AY+MIBEReqqLuywsLCwsLA==",
      "token": "7",
      "enabled": true,
      "version": "1",
      "createdAt": "2026-06-30T14:00:00Z",
      "updatedAt": "2026-06-30T14:00:00Z",
      "health": {
        "sessionId": "AY+MJTQ0NDQ0NDQ0NDQ0NA==",
        "workspaceId": "AY+MHnorfD2eTxorPE1ebw==",
        "healthy": true,
        "latencyMs": 88,
        "consecutiveFailures": 0,
        "lastSuccessAt": "2026-06-30T14:05:00Z",
        "probedAt": "2026-06-30T14:05:00Z"
      },
      "slot": 7
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjUwfQ=="
}