> For the complete documentation index, see [llms.txt](https://docs.marsproxies.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marsproxies.com/marsproxies-documentation/overview/residential-proxies/api/access.md).

# Access

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

## Generate residential proxy connection strings

> 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.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-access","description":"Residential access data — countries, regions, country sets, proxy list generation"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"GenerateProxyListRequest":{"title":"Generate Proxy List Request","description":"Parameters for generating a list of residential proxy connection strings. Provide either `subuser_hash` or both `username` and `password` to target a specific subuser.","properties":{"format":{"description":"Template used to render each proxy connection string.","type":"string","enum":["{hostname}:{port}:{username}:{password}","{hostname}:{port}@{username}:{password}","{username}:{password}:{hostname}:{port}"]},"hostname":{"description":"Proxy gateway hostname or its resolved IP. Must match one of the configured gateways.","type":"string"},"port":{"description":"Named proxy port — `http` or `socks5`. See the [Protocols](../proxy/protocols) page for details on each protocol.","type":"string"},"rotation":{"description":"Session rotation mode. `sticky` keeps the same IP for the `lifetime` window; `random` rotates each request. See the [Rotation](../proxy/rotation) page for more on session rotation behaviour.","type":"string","enum":["sticky","random"]},"lifetime":{"description":"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](../proxy/rotation) page for more on session rotation behaviour.","type":["string","null"]},"subuser_hash":{"description":"Subuser hash to target. Required unless `username` and `password` are provided.","type":["string","null"]},"username":{"description":"Subuser username. Required unless `subuser_hash` is provided.","type":["string","null"]},"password":{"description":"Subuser password. Required unless `subuser_hash` is provided.","type":["string","null"]},"location":{"description":"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](../proxy/location) page for the full list of supported segments and examples.","type":["string","null"]},"proxy_count":{"description":"Number of proxy connection strings to generate. Default to 10.","type":["integer","null"]}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}},"ValidationErrorEnvelopeDTO":{"title":"Validation Error Envelope","description":"Validation error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ValidationErrorResponseDTO"}},"type":"object","xml":{"name":"ValidationErrorEnvelopeDTO"}},"ValidationErrorResponseDTO":{"title":"Validation Error Response","description":"Validation error response with per-field error details","required":["code","message","detailed_messages"],"properties":{"code":{"title":"code","description":"Error code — always \"failed_validation\" for validation errors","type":"string"},"message":{"title":"message","description":"Pipe-separated concatenation of all validation error messages","type":"string"},"detailed_messages":{"title":"detailed_messages","description":"Object mapping field names to arrays of validation error messages for that field","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object","xml":{"name":"ValidationErrorResponseDTO"}},"GenerateProxyListActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"format":{"type":"array","items":{"type":"string","enum":["The selected format is invalid."]}},"hostname":{"type":"array","items":{"type":"string","enum":["The selected hostname is invalid."]}},"port":{"type":"array","items":{"type":"string","enum":["The selected port is invalid."]}},"rotation":{"type":"array","items":{"type":"string","enum":["The selected rotation is invalid."]}},"lifetime":{"type":"array","items":{"type":"string","enum":["The selected lifetime is invalid. Must be `{N}s` (1-59), `{N}m` (1-59), or `{N}h` (1-168)."]}},"subuser_hash":{"type":"array","items":{"type":"string","enum":["The subuser hash field is required when username / password are not present.","The subuser hash must be a string.","The selected subuser hash is invalid."]}},"username":{"type":"array","items":{"type":"string","enum":["The username field is required when subuser hash is not present.","The username must be a string."]}},"password":{"type":"array","items":{"type":"string","enum":["The password field is required when subuser hash is not present.","The password must be a string."]}},"location":{"type":"array","items":{"type":"string","enum":["The location must be a string."]}},"proxy_count":{"type":"array","items":{"type":"string","enum":["The proxy count must be an integer.","The proxy count must be between 1 and the configured maximum."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/access/generate-proxy-list":{"post":{"tags":["residential-access"],"summary":"Generate residential proxy connection strings","description":"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.","operationId":"generateResidentialProxyList","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateProxyListRequest"}}}},"responses":{"200":{"description":"Generated proxy connection strings","content":{"application/json":{"schema":{"description":"Array of rendered proxy connection strings","type":"array","items":{"type":"string"}}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record or subuser credentials not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"409":{"description":"Semantic validation error: the supplied `location` segment, `username`, or `password` does not match an existing record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelopeDTO"}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateProxyListActionValidationError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```

## List residential access countries

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

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-access","description":"Residential access data — countries, regions, country sets, proxy list generation"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"CountriesResponse":{"title":"Countries Response","description":"List of countries available for residential proxy location targeting.","required":["prefix","countries"],"properties":{"prefix":{"description":"Prefix to prepend to each country code when building a location string.","type":"string"},"countries":{"description":"Available countries. Each country can include nested cities and states.","type":"array","items":{"$ref":"#/components/schemas/CountryResource"}}},"type":"object"},"CountryResource":{"title":"Country Resource","description":"A country available for residential proxy targeting, with optional cities and states.","required":["code","name","cities"],"properties":{"code":{"description":"Two-letter ISO country code used as the segment value after \"_country-\".","type":"string"},"name":{"description":"Country name.","type":"string"},"cities":{"$ref":"#/components/schemas/AccessSubLocationResource","description":"Cities available under this country."},"states":{"$ref":"#/components/schemas/AccessSubLocationResource","description":"States or regions available under this country."}},"type":"object"},"AccessSubLocationResource":{"title":"Access Sub-Location Resource","description":"A prefixed list of sub-location options (cities or states) nested under a country.","required":["prefix","options"],"properties":{"prefix":{"description":"Prefix to prepend to each option code when building a location string.","type":"string"},"options":{"description":"Available sub-location options for this country.","type":"array","items":{"$ref":"#/components/schemas/AccessOptionResource"}}},"type":"object"},"AccessOptionResource":{"title":"Access Option Resource","description":"A single named option (region, country set, city, state) used when building a residential location string.","required":["code","name"],"properties":{"code":{"description":"Segment value appended after the location prefix (e.g. \"us\", \"eu\", \"california\").","type":"string"},"name":{"description":"Human-readable option name.","type":"string"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}}}},"paths":{"/v1/residential/access/countries":{"get":{"tags":["residential-access"],"summary":"List residential access countries","description":"Returns the catalog of countries available for residential proxy location targeting, with their nested cities and states.","operationId":"getResidentialAccessCountries","responses":{"200":{"description":"Available countries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record not found for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```

## List residential access country sets

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

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-access","description":"Residential access data — countries, regions, country sets, proxy list generation"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"CountrySetsResponse":{"title":"Country Sets Response","description":"List of country sets (pre-grouped country bundles) available for residential proxy targeting.","required":["prefix","country_sets"],"properties":{"prefix":{"description":"Prefix to prepend to each country set code when building a location string.","type":"string"},"country_sets":{"description":"Available country sets.","type":"array","items":{"$ref":"#/components/schemas/AccessOptionResource"}}},"type":"object"},"AccessOptionResource":{"title":"Access Option Resource","description":"A single named option (region, country set, city, state) used when building a residential location string.","required":["code","name"],"properties":{"code":{"description":"Segment value appended after the location prefix (e.g. \"us\", \"eu\", \"california\").","type":"string"},"name":{"description":"Human-readable option name.","type":"string"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}}}},"paths":{"/v1/residential/access/country-sets":{"get":{"tags":["residential-access"],"summary":"List residential access country sets","description":"Returns the catalog of country sets (pre-grouped country bundles) available for residential proxy location targeting.","operationId":"getResidentialAccessCountrySets","responses":{"200":{"description":"Available country sets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountrySetsResponse"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record not found for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```

## List residential access regions

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

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-access","description":"Residential access data — countries, regions, country sets, proxy list generation"}],"servers":[{"url":"https://api.marsproxies.com","description":"MarsProxies API"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer","description":"API token generated in the MarsProxies dashboard under /settings. Send it as a Bearer token in the Authorization header."}},"schemas":{"RegionsResponse":{"title":"Regions Response","description":"List of regions available for residential proxy location targeting.","required":["prefix","regions"],"properties":{"prefix":{"description":"Prefix to prepend to each region code when building a location string.","type":"string"},"regions":{"description":"Available regions.","type":"array","items":{"$ref":"#/components/schemas/AccessOptionResource"}}},"type":"object"},"AccessOptionResource":{"title":"Access Option Resource","description":"A single named option (region, country set, city, state) used when building a residential location string.","required":["code","name"],"properties":{"code":{"description":"Segment value appended after the location prefix (e.g. \"us\", \"eu\", \"california\").","type":"string"},"name":{"description":"Human-readable option name.","type":"string"}},"type":"object"},"ErrorEnvelopeDTO":{"title":"Error Envelope","description":"Error response envelope","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorResponseDTO"}},"type":"object","xml":{"name":"ErrorEnvelopeDTO"}},"ErrorResponseDTO":{"title":"Error Response","description":"Error Response","required":["code","message","trace_id"],"properties":{"code":{"title":"code","description":"Error code","type":"string"},"message":{"title":"message","description":"Error message","type":"string"},"trace_id":{"title":"trace_id","description":"Request trace ID for correlating logs and support requests","type":"string"}},"type":"object","xml":{"name":"ErrorResponseDTO"}}}},"paths":{"/v1/residential/access/regions":{"get":{"tags":["residential-access"],"summary":"List residential access regions","description":"Returns the catalog of regions available for residential proxy location targeting.","operationId":"getResidentialAccessRegions","responses":{"200":{"description":"Available regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionsResponse"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"403":{"description":"Residential API is not enabled for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"404":{"description":"Residential user record not found for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"500":{"description":"Unknown error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}}}}}}}
```