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.
/ proxies. v1. Proxies/ ImportProxyListRequest 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?stringOpaque 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?stringName 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
hoststringEndpoint host name or IP address. Required. An invalid host fails the row.
password?stringPassword for proxy authentication. Write only: stored encrypted and never returned. Empty for an endpoint that authenticates by IP address.
port?integerEndpoint TCP port, from 1 to 65535. Any other value fails the row.
Format"int32"
scheme?stringProtocol used to connect: "http", "https" or "socks5". Empty means "http".
username?stringUsername for proxy authentication. Empty for an endpoint that authenticates by IP address.
Response body
application/json
Success
addedCount?integerHow many rows added a new session to the pool.
Format"int32"
alreadyInPoolCount?integerHow many valid rows added nothing because the pool already held the proxy, including repeats inside this request.
Format"int32"
poolId?stringOpaque 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?booleanTrue 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?ImportProxyListErrorWhy the row failed. Set when it was not imported.
Show attributes
code?stringThe 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_"IMPORT_
message?stringHuman-readable detail of the failure.
sessionId?stringOpaque 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
application/json
The request was malformed, such as a missing required field or an unparseable cursor. The request cannot be carried out in the current system state.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The request lacks a valid API key in the Authorization header.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The API key is not allowed to perform this action on this workspace.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The resource already exists.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The request was rate limited. Slow down and retry later.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
An internal server error occurred.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The service is temporarily unavailable. Retry with backoff.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
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
}
]
}'const res = await fetch("https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"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
}
]
}),
});
const data = await res.json();body := strings.NewReader(`{
"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
}
]
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList", body)
if err != nil {
return err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("CSTRADER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)import os, requests
res = requests.post(
"https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"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
}
]
},
)
data = res.json(){
"poolId": "AY+MISIifMyN3T09PT09PQ==",
"results": [
{
"sessionId": "AY+MIjMzfu6P/05OTk5OTg=="
},
{
"error": {
"code": "IMPORT_PROXY_LIST_ERROR_CODE_INVALID",
"message": "invalid host"
}
}
],
"addedCount": 1
}{
"code": "failed_precondition",
"message": "The request cannot be carried out in the current system state."
}{
"code": "unauthenticated",
"message": "The request lacks a valid API key in the Authorization header."
}{
"code": "permission_denied",
"message": "The API key is not allowed to perform this action on this workspace."
}{
"code": "already_exists",
"message": "The resource already exists."
}{
"code": "resource_exhausted",
"message": "The request was rate limited. Slow down and retry later."
}{
"code": "internal",
"message": "An internal server error occurred."
}{
"code": "unavailable",
"message": "The service is temporarily unavailable. Retry with backoff."
}curl -X POST "https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList" \
-H "Authorization: Bearer $CSTRADER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"addToPoolId": "AY+MISIifMyN3T09PT09PQ==",
"rows": [
{
"scheme": "http",
"host": "203.0.113.10",
"port": 8080,
"username": "u1",
"password": "p1"
},
{
"scheme": "http",
"host": "203.0.113.12",
"port": 8080,
"username": "u1",
"password": "p1"
}
]
}'const res = await fetch("https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"addToPoolId": "AY+MISIifMyN3T09PT09PQ==",
"rows": [
{
"scheme": "http",
"host": "203.0.113.10",
"port": 8080,
"username": "u1",
"password": "p1"
},
{
"scheme": "http",
"host": "203.0.113.12",
"port": 8080,
"username": "u1",
"password": "p1"
}
]
}),
});
const data = await res.json();body := strings.NewReader(`{
"addToPoolId": "AY+MISIifMyN3T09PT09PQ==",
"rows": [
{
"scheme": "http",
"host": "203.0.113.10",
"port": 8080,
"username": "u1",
"password": "p1"
},
{
"scheme": "http",
"host": "203.0.113.12",
"port": 8080,
"username": "u1",
"password": "p1"
}
]
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList", body)
if err != nil {
return err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("CSTRADER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)import os, requests
res = requests.post(
"https://api.goldmine.to/proxies.v1.Proxies/ImportProxyList",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"addToPoolId": "AY+MISIifMyN3T09PT09PQ==",
"rows": [
{
"scheme": "http",
"host": "203.0.113.10",
"port": 8080,
"username": "u1",
"password": "p1"
},
{
"scheme": "http",
"host": "203.0.113.12",
"port": 8080,
"username": "u1",
"password": "p1"
}
]
},
)
data = res.json(){
"poolId": "AY+MISIifMyN3T09PT09PQ==",
"results": [
{
"sessionId": "AY+MIjMzfu6P/05OTk5OTg==",
"alreadyInPool": true
},
{
"sessionId": "AY+MJTQ0NDQ0NDQ0NDQ0NA=="
}
],
"addedCount": 1,
"alreadyInPoolCount": 1
}{
"code": "failed_precondition",
"message": "The request cannot be carried out in the current system state."
}{
"code": "unauthenticated",
"message": "The request lacks a valid API key in the Authorization header."
}{
"code": "permission_denied",
"message": "The API key is not allowed to perform this action on this workspace."
}{
"code": "already_exists",
"message": "The resource already exists."
}{
"code": "resource_exhausted",
"message": "The request was rate limited. Slow down and retry later."
}{
"code": "internal",
"message": "An internal server error occurred."
}{
"code": "unavailable",
"message": "The service is temporarily unavailable. Retry with backoff."
}