Access

Residential access data — countries, regions, country sets, proxy list generation

Generate residential proxy connection strings

post

Generates a list of residential proxy connection strings for a subuser, rendered in the requested format with the chosen gateway, port, rotation mode, and location targeting.

Authorizations

api_token

AuthorizationstringRequired

API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header.

Body

application/json

Parameters for generating a list of residential proxy connection strings. Provide either subuser_hash or both username and password to target a specific subuser.

formatstring · enumOptional

Template used to render each proxy connection string.

Example: {hostname}:{port}:{username}:{password}Possible values:

hostnamestringOptional

Proxy gateway hostname or its resolved IP. Must match one of the configured gateways.

Example: ultra.marsproxies.com

portstringOptional

Named proxy port — http or socks5. See the Protocols page for details on each protocol.

Example: http

rotationstring · enumOptional

Session rotation mode. sticky keeps the same IP for the lifetime window; random rotates each request. See the Rotation page for more on session rotation behaviour.

Example: stickyPossible values:

lifetimestring · nullableOptional

Sticky session lifetime. Required when rotation=sticky. Format: {N}s (1-59), {N}m (1-59), or {N}h (1-168). Defaults to 24h. See the Rotation page for more on session rotation behaviour.

Example: 30m

subuser_hashstring · nullableOptional

Subuser hash to target. Required unless username and password are provided.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

usernamestring · nullableOptional

Subuser username. Required unless subuser_hash is provided.

Example: mr12345ab1c

passwordstring · nullableOptional

Subuser password. Required unless subuser_hash is provided.

Example: Maf83Kz7k2

locationstring · nullableOptional

Location targeting string built from prefixed segments joined with underscores — e.g. _country-us_city-dallas or _region-europe. Leave empty for global targeting. See the Location page for the full list of supported segments and examples.

Example: _country-us_city-dallas

proxy_countinteger · nullableOptional

Number of proxy connection strings to generate. Default to 10.

Example: 10

Responses

200

Generated proxy connection strings

application/json

string[]Optional

Array of rendered proxy connection strings

Example: ultra.marsproxies.com:44443:mr42a1b2:Mxa8Kz7k2

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Residential user record or subuser credentials not found

application/json

409

Semantic validation error: the supplied location segment, username, or password does not match an existing record

application/json

422

Request body validation failed

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

post/v1/residential/access/generate-proxy-list

cURLPHPPythonNode.jsJavaGoC#

curl --request POST \
  --url https://api.marsproxies.com/v1/residential/access/generate-proxy-list \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"format":"{hostname}:{port}:{username}:{password}","hostname":"ultra.marsproxies.com","port":"http","rotation":"sticky","lifetime":"30m","subuser_hash":"A1B2C3D4E5F6G7H8I9J0K1L2M3","username":"mr12345ab1c","password":"Maf83Kz7k2","location":"_country-us_city-dallas","proxy_count":10}'

[
  "ultra.marsproxies.com:44443:mr42a1b2:Mxa8Kz7k2"
]

List residential access countries

get

Returns the catalog of countries available for residential proxy location targeting, with their nested cities and states.

Authorizations

api_token

AuthorizationstringRequired

API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header.

Responses

200

Available countries

application/json

List of countries available for residential proxy location targeting.

prefixstringRequired

Prefix to prepend to each country code when building a location string.

Example: _country-

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Residential user record not found for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

get/v1/residential/access/countries

cURLPHPPythonNode.jsJavaGoC#

curl --request GET \
  --url https://api.marsproxies.com/v1/residential/access/countries \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

{
  "prefix": "_country-",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "cities": {
        "prefix": "_city-",
        "options": [
          {
            "code": "us",
            "name": "United States"
          }
        ]
      },
      "states": {
        "prefix": "_city-",
        "options": [
          {
            "code": "us",
            "name": "United States"
          }
        ]
      }
    }
  ]
}

List residential access country sets

get

Returns the catalog of country sets (pre-grouped country bundles) available for residential proxy location targeting.

Authorizations

api_token

AuthorizationstringRequired

API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header.

Responses

200

Available country sets

application/json

List of country sets (pre-grouped country bundles) available for residential proxy targeting.

prefixstringRequired

Prefix to prepend to each country set code when building a location string.

Example: _set-

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Residential user record not found for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

get/v1/residential/access/country-sets

cURLPHPPythonNode.jsJavaGoC#

curl --request GET \
  --url https://api.marsproxies.com/v1/residential/access/country-sets \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

{
  "prefix": "_set-",
  "country_sets": [
    {
      "code": "us",
      "name": "United States"
    }
  ]
}

List residential access regions

get

Returns the catalog of regions available for residential proxy location targeting.

Authorizations

api_token

AuthorizationstringRequired

API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header.

Responses

200

Available regions

application/json

List of regions available for residential proxy location targeting.

prefixstringRequired

Prefix to prepend to each region code when building a location string.

Example: _region-

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Residential user record not found for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

get/v1/residential/access/regions

cURLPHPPythonNode.jsJavaGoC#

curl --request GET \
  --url https://api.marsproxies.com/v1/residential/access/regions \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

{
  "prefix": "_region-",
  "regions": [
    {
      "code": "us",
      "name": "United States"
    }
  ]
}