Skip to content

API Reference / Proxy pools

Import a proxy list into a pool

Turns an uploaded list of proxies into ready-to-use sessions in one call. Without add_to_pool_id it creates a new provider-less pool named pool_name. With it the rows go into that existing imported pool, so a long list can be sent in batches. A proxy the pool already holds (same scheme, username, host and port) is not added again and keeps its stored password, so sending the same batch twice is safe. Each row is processed independently and the response reports per-row success or error with counts. Limited per workspace to 60 calls a minute with a burst of 20. A refused call is resource_exhausted with the rate limited reason and a retry time.

POST/proxies.v1.Proxies/ImportProxyList

Request body

application/jsonRequired

Request to add a list of proxy endpoints to a new pool, or to an existing imported pool, one session per valid row. Invalid rows are reported individually and not imported.

addToPoolId?string

Opaque 16-byte identifier of an existing imported pool to add the rows to, base64-encoded in JSON. Empty creates a new pool named pool_name. A pool of another workspace, or one that does not exist, is not_found. A pool a provider owns is failed_precondition with the provider owned reason.

Format"byte" base64

poolName?string

Name of the new pool. Empty names it "import" followed by the current UTC date and time. Must be empty when add_to_pool_id is set.

rows?array<ProxyImportRow>

The endpoints to import, at most 10000. More is rejected with invalid_argument.

Show attributes
hoststring

Endpoint host name or IP address. Required. An invalid host fails the row.

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. Any other value fails the row.

Format"int32"

scheme?string

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

username?string

Username for proxy authentication. Empty for an endpoint that authenticates by IP address.

Response body

application/json

Success

addedCount?integer

How many rows added a new session to the pool.

Format"int32"

alreadyInPoolCount?integer

How many valid rows added nothing because the pool already held the proxy, including repeats inside this request.

Format"int32"

poolId?string

Opaque 16-byte identifier of the pool the rows went into, base64-encoded in JSON: the new pool, or add_to_pool_id.

Format"byte" base64

results?array<ImportProxyRowResult>

The outcome of each row, in request order.

Show attributes
alreadyInPool?boolean

True when the pool already held this proxy, from an earlier batch or an earlier row of this one, so nothing was added and session_id is the existing session.

error?ImportProxyListError

Why the row failed. Set when it was not imported.

Show attributes
code?string

The kind of failure. Invalid means the row's host, port or scheme could not be used. Address not allowed means its host is, or resolves to, an internal address.

Value in"IMPORT_PROXY_LIST_ERROR_CODE_INVALID""IMPORT_PROXY_LIST_ERROR_CODE_ADDRESS_NOT_ALLOWED"

message?string

Human-readable detail of the failure.

sessionId?string

Opaque 16-byte identifier of the session that holds this row, base64-encoded in JSON: the one created for it, or the one the pool already had. Set when the row was valid.

Format"byte" base64

curl -X POST "https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "poolName": "imported-proxies",
    "rows": [
      {
        "scheme": "http",
        "host": "203.0.113.10",
        "port": 8080,
        "username": "u1",
        "password": "p1"
      },
      {
        "scheme": "socks5",
        "host": "203.0.113.11",
        "port": 1080
      }
    ]
  }'
{
  "poolId": "AY+MISIifMyN3T09PT09PQ==",
  "results": [
    {
      "sessionId": "AY+MIjMzfu6P/05OTk5OTg=="
    },
    {
      "error": {
        "code": "IMPORT_PROXY_LIST_ERROR_CODE_INVALID",
        "message": "invalid host"
      }
    }
  ],
  "addedCount": 1
}