# Overview

MarsProxies provides residential proxies with rotating and sticky sessions, global geo-targeting, and HTTP, HTTPS, and SOCKS5 support for web scraping, SEO monitoring, and market research.

MarsProxies provides residential proxies for reliable data collection.

Use rotating proxies or sticky sessions for web scraping, SEO monitoring, market research, ad verification, and geo-targeted browsing.

Our network includes over 1 million ethically sourced IPs across 190+ locations.

You can:

* Connect over HTTP, HTTPS, or SOCKS5
* Target by country, state, or city
* Scale from small tests to large data collection jobs

### Why teams use MarsProxies

* **Global residential proxy coverage** for location-based testing and local data collection
* **Rotating and sticky sessions** for both high-volume scraping and session-based tasks
* **HTTP, HTTPS, and SOCKS5 support** for broad tool and browser compatibility
* **Dual authentication** with username and password or IP whitelisting
* **24/7 support** for setup help and technical issues

### Common use cases

* Web scraping and large-scale data extraction
* SEO monitoring and search engine results tracking
* Market research, price monitoring, and competitor analysis
* Ad verification and geo-targeted QA
* Social media management and multi-location testing

### Start here

#### For your account

* [Pricing](https://marsproxies.com/pricing): pay-as-you-go and monthly plans
* [Sign up](https://marsproxies.com/register/): get started in a few minutes
* [Dashboard](https://dashboard.marsproxies.com/): generate API tokens, manage traffic, and view usage

#### Get started in 3 steps

{% stepper %}
{% step %}

### Sign up and buy your first GB

Create an account and buy at least 1 GB of residential traffic. This unlocks API access and the full dashboard.
{% endstep %}

{% step %}

### Generate an access token

Open the dashboard, then go to **Settings** → **API**. Generate a personal access token and store it safely. 
{% endstep %}

{% step %}

### Make your first request

Build your proxy string in [Proxy](/marsproxies-documentation/overview/residential-proxies/proxy) or use token-based access in [API](/marsproxies-documentation/overview/residential-proxies/api).
{% endstep %}
{% endstepper %}

#### Help and community

* [Status page](https://status.marsproxies.com): live network health
* Sales: <sales@marsproxies.com>
* Support: <support@marsproxies.com> or in-app chat


# Residential Proxies

MarsProxies offers over 1 million residential proxies across 190+ locations worldwide.

Our ethically sourced IP pool keeps growing, so you get reliable proxies for data collection, testing, and automation.

***

### Key advantages

* **Budget-friendly pricing** **·** Competitive plans work for solo users, teams, and enterprises. Save up to 67% on higher-volume plans.
* **Ethically sourced proxy pool** **·** Every IP comes from a real device and a legitimate ISP, with explicit partner consent. This means cleaner IPs and better success rates.
* **Granular geo-targeting** **·** Target by country, state, or city across 190+ locations at no extra cost.
* **No commitments** **·** Choose monthly billing or pay as you go. There are no long-term contracts or hidden fees.
* **Non-expiring traffic** **·** Your purchased bandwidth stays in your account until you use it.
* **24/7 support** **·** Get help anytime through live chat or Discord.

### Technical features

* **Flexible session control** **·** Rotate IPs on every request, or keep a sticky session from 1 second to 7 days.
* **HTTP/HTTPS and SOCKS5 support** **·** Use MarsProxies with HTTP, HTTPS, or SOCKS5 tools, browsers, and bots.
* **Dual authentication** **·** Authenticate with a username and password, or whitelist your IP address.
* **High success rate** **·** Residential IPs average a 98.4% success rate, which helps reduce blocks, CAPTCHAs, and failed requests.
* **Software compatibility** **·** MarsProxies works with many tools and apps. Use the [integration guides](https://marsproxies.com/blog/category/integration-tutorial/) to get started faster.

***

### Common use cases

* Web scraping
* Bypassing geo-restrictions
* Social media management
* Market research
* SEO monitoring
* Ad verification


# Proxy

This section walks you through building and configuring a proxy string. You'll learn how to target specific locations, set up rotation preferences, choose the right protocol, and more. We'll also show you how to make a request using your proxy.

First, it helps to know that every proxy string is made up of four components: **host**, **port**, **username**, and **password**. These can be arranged in different ways, but throughout this documentation we'll use the following format: `HOST:PORT:USERNAME:PASSWORD`.

With residential proxies, the **password** field does more than just authenticate — it's also where you define your proxy configuration settings (such as location targeting and rotation behavior).

Here's an example proxy string configured to target the state of Texas in the USA:

```
ultra.marsproxies.com:44443:username123:password123_country-us_state-texas
```

Breaking this down, the string consists of four colon-separated sections:

* **Host** — `ultra.marsproxies.com` — the proxy server address you connect to
* **Port** — `44443` — the port number used for the connection
* **Username** — `username123` — your account username
* **Password** — `password123_country-us_state-texas` — your base password followed by configuration parameters

The **password section** is where all proxy settings are appended. Configuration parameters are added directly after your password using an underscore (`_`) as a separator. In the example above, `_country-us` specifies the target country (United States) and `_state-texas` narrows it down to the state of Texas.

The following pages cover each available configuration option in detail.


# Location

Location targeting is one of the most important aspects of setting up your proxy. Whether you need to appear in a specific country, region, state, or city, MarsProxies gives you flexible options to dial in exactly where your traffic should appear to come from. The following sections break down each available targeting parameter.

***

#### Region

`_region-` is the parameter used to target a broad geographic region. Appending this to your password field instructs the proxy router to serve an exit node from within that region.

**Example:**

```
ultra.marsproxies.com:44443:username123:password123_region-europe
```

***

#### Country

`_country-` is the parameter used to target a specific country. The value must be a two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.

You can specify more than one country at a time by separating codes with a comma. When multiple countries are provided, the router will randomly select one of them when assigning an exit node.

**Example (multiple countries):**

```
ultra.marsproxies.com:44443:username123:password123_country-es,fr,it
```

***

#### City

`_city-` is the parameter used to target a specific city. The value should be the name of the city.

> **Note:** When targeting a city, always include the country parameter as well. Many cities share the same name across different countries, and specifying the country ensures you get the correct location.

**Example:**

```
ultra.marsproxies.com:44443:username123:password123_country-de_city-berlin
```

***

#### State

`_state-` is used to target a specific state within the United States. The value should be the full name of the state.

> **Note:** Make sure to also set the country to `us` when using state targeting.

**Example:**

```
ultra.marsproxies.com:44443:username123:password123_country-us_state-iowa
```


# Rotation

MarsProxies residential proxies support two session rotation modes: **Sticky** and **Randomize**. Each mode is designed for different use cases, so you can choose the one that best fits your workflow.

### Sticky

Sticky sessions let you hold onto the same proxy IP for a set period of time. This is useful when your task requires a continuous connection from the same address — for example, when interacting with websites that use session-based authentication or track your activity across multiple requests.

Two parameters control how sticky sessions work:

* **`_session-`** — Tells the routing system to create or maintain a specific session. The value must be a random alphanumeric string that is **exactly 8 characters long**, which guarantees each session is unique.
* **`_lifetime-`** — Sets how long the session stays active. The minimum is **1 second** and the maximum is **7 days**. Keep in mind that only a single time unit can be specified per value.

**Example:**

```
ultra.marsproxies.com:44443:username123:password123_country-br_session-fsiwjtqc_lifetime-10m
```

### Randomize

With randomized rotation, a fresh proxy IP is assigned on every request. This makes it the ideal choice for tasks that demand a high degree of anonymity, such as web scraping or browsing without a traceable pattern.

No additional parameters are needed in your proxy string to use this mode — it works out of the box.

{% hint style="info" %}
To reduce IP rotation frequency and improve proxy performance, add the `_forcerandom-1` tag to your proxy string. This expands the pool of available IPs to select from.
{% endhint %}


# Protocols

## Protocols

MarsProxies residential proxies support two main protocol types: **HTTP/HTTPS** and **SOCKS5**. Each operates differently and is suited to different use cases, so choosing the right one depends on what you're trying to accomplish.

{% hint style="info" %}
MarsProxies residential proxies support **TCP** connections.
{% endhint %}

### HTTP/HTTPS

HTTP is the standard protocol for web-based traffic and is the most commonly used option. It works well for browsing websites and handling general web requests. When security is a priority — such as when transmitting sensitive information — HTTPS builds on top of HTTP by encrypting the data exchanged between your client and the destination server, keeping that communication private and secure.

### SOCKS5

SOCKS5 is a more flexible protocol that isn't limited to web traffic. It can handle a wide variety of connection types, making it a great choice for tasks like P2P file sharing or VoIP applications. Compared to HTTP/HTTPS, SOCKS5 proxies run on different ports and offer broader compatibility across different traffic types, along with solid performance and security.


# Sub-users

MarsProxies includes a sub-user feature built to support reseller workflows, giving you the ability to grow and manage a business built on top of our infrastructure. With this feature, you can provision and oversee multiple sub-users under a single account, making it easy to offer proxy access to your own clients or distribute usage across teams and projects.

Traffic allocated to sub-users is drawn from your main account balance.

Sub-user management is available via [the API](broken://pages/10f7e2ab82b1f31cd8d0248c9667497715390f13) where you can **create** new sub-users (assigning them a username, password, and traffic allocation), **update** existing sub-users (changing credentials, adjusting traffic), **delete** sub-users when they're no longer needed, and **give or take traffic** between your main account and any sub-user at any time.


# API

All requests are authenticated using the `Authorization` header. Every request must include this header with your API token as the value, preceded by the word `Bearer` and a single space:

```
Authorization: Bearer <your_api_token>
```

After purchasing 1GB or more of Residential data, you can find your API token on the [**Settings**](https://dashboard.marsproxies.com/settings) page of your dashboard, under the **API** section. If needed, you can generate a new token from the same location. Make sure to store your token safely. If you ever reset it, remember to update any applications or integrations that rely on it.


# Account

Residential account data — traffic, subuser count, hash

## Get residential account summary

> Returns summary for the main residential account — available traffic, subuser count, and account hash.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential","description":"Residential account data — traffic, subuser count, hash"}],"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":{"ResidentialUserResource":{"title":"Residential User Resource","description":"Summary of the main residential account.","required":["traffic_available","subusers_count","hash"],"properties":{"traffic_available":{"description":"Residential traffic currently available, in gigabytes.","type":"number","format":"float"},"subusers_count":{"description":"Number of residential subusers owned by this account.","type":"integer"},"hash":{"description":"Residential account hash.","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/me":{"get":{"tags":["residential"],"summary":"Get residential account summary","description":"Returns summary for the main residential account — available traffic, subuser count, and account hash.","operationId":"getResidentialUser","responses":{"200":{"description":"Residential account summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialUserResource"}}}},"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"}}}}}}}}}
```


# Sub-users

Residential sub-user management — create, list, update, delete, traffic transfers

## List residential subusers

> Returns a paginated list of residential subusers owned by the account, optionally filtered by username or internal id.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"ResidentialSubuserCollection":{"title":"Residential Subuser Collection","description":"Paginated list of residential subusers.","required":["data"],"properties":{"data":{"description":"Subusers on the current page.","type":"array","items":{"$ref":"#/components/schemas/ResidentialSubuserResource"}}},"type":"object"},"ResidentialSubuserResource":{"title":"Residential Subuser Resource","description":"A residential subuser owned by the account.","required":["id","hash","username","password","traffic_available","traffic_used"],"properties":{"id":{"description":"Internal subuser identifier.","type":"integer"},"hash":{"description":"Subuser hash used to reference the subuser in API requests.","type":"string"},"username":{"description":"Subuser proxy username.","type":"string"},"password":{"description":"Subuser proxy password.","type":"string"},"traffic_available":{"description":"Traffic currently allocated to this subuser, in gigabytes.","type":"number","format":"float"},"traffic_used":{"description":"Traffic already consumed by this subuser, in gigabytes.","type":"number","format":"float"}},"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"}},"GetSubusersActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"page":{"type":"array","items":{"type":"string","enum":["The page must be an integer.","The page must be at least 1.","The page must not be greater than 10000."]}},"per_page":{"type":"array","items":{"type":"string","enum":["The per page must be an integer.","The per page must be at least 1.","The per page must not be greater than the configured maximum."]}},"search":{"type":"array","items":{"type":"string","enum":["The search must be a string.","The search must be at least 1 character.","The search must not be greater than 30 characters."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers":{"get":{"tags":["residential-subusers"],"summary":"List residential subusers","description":"Returns a paginated list of residential subusers owned by the account, optionally filtered by username or internal id.","operationId":"getResidentialSubusers","parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Number of subusers per page.","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","description":"Filter by subuser username (partial match) or exact internal id. 1-30 characters.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated residential subusers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialSubuserCollection"}}}},"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"}}}},"422":{"description":"Pagination or search parameters failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubusersActionValidationError"}}}},"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"}}}}}}}}}
```

## Create a residential subuser

> Creates a new residential subuser under the account. If \`username\` or \`password\` are omitted the server generates them. If \`traffic\` is provided the requested amount is transferred from the reseller's balance to the new subuser.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"CreateSubuserRequest":{"title":"Create Subuser Request","description":"Payload for creating a residential subuser. All fields are optional — server generates a random username and password when omitted.","properties":{"username":{"description":"Desired subuser username. 3-30 alphanumeric or underscore characters.","type":["string","null"]},"password":{"description":"Desired subuser password. 6-16 alphanumeric characters.","type":["string","null"]},"traffic":{"description":"Initial traffic to allocate to the subuser, in gigabytes. Must not exceed the main account's available traffic.","type":["number","null"],"format":"float"}},"type":"object"},"ResidentialSubuserResource":{"title":"Residential Subuser Resource","description":"A residential subuser owned by the account.","required":["id","hash","username","password","traffic_available","traffic_used"],"properties":{"id":{"description":"Internal subuser identifier.","type":"integer"},"hash":{"description":"Subuser hash used to reference the subuser in API requests.","type":"string"},"username":{"description":"Subuser proxy username.","type":"string"},"password":{"description":"Subuser proxy password.","type":"string"},"traffic_available":{"description":"Traffic currently allocated to this subuser, in gigabytes.","type":"number","format":"float"},"traffic_used":{"description":"Traffic already consumed by this subuser, in gigabytes.","type":"number","format":"float"}},"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"}},"CreateSubuserActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"username":{"type":"array","items":{"type":"string","enum":["The username must be a string.","The username format is invalid.","The username must be at least 3 characters.","The username must not be greater than 30 characters."]}},"password":{"type":"array","items":{"type":"string","enum":["The password must be a string.","The password must only contain letters and numbers.","The password must be at least 6 characters.","The password must not be greater than 16 characters."]}},"traffic":{"type":"array","items":{"type":"string","enum":["The traffic must be a number.","The traffic must be greater than 0."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers":{"post":{"tags":["residential-subusers"],"summary":"Create a residential subuser","description":"Creates a new residential subuser under the account. If `username` or `password` are omitted the server generates them. If `traffic` is provided the requested amount is transferred from the reseller's balance to the new subuser.","operationId":"createResidentialSubuser","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubuserRequest"}}}},"responses":{"200":{"description":"Newly created subuser","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialSubuserResource"}}}},"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"}}}},"409":{"description":"Username is already taken, or the main account does not have enough traffic to allocate to the new subuser","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelopeDTO"}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubuserActionValidationError"}}}},"423":{"description":"A traffic-mutating operation is already in progress 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"}}}}}}}}}
```

## Get a residential subuser

> Returns a single residential subuser owned by the account.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"ResidentialSubuserResource":{"title":"Residential Subuser Resource","description":"A residential subuser owned by the account.","required":["id","hash","username","password","traffic_available","traffic_used"],"properties":{"id":{"description":"Internal subuser identifier.","type":"integer"},"hash":{"description":"Subuser hash used to reference the subuser in API requests.","type":"string"},"username":{"description":"Subuser proxy username.","type":"string"},"password":{"description":"Subuser proxy password.","type":"string"},"traffic_available":{"description":"Traffic currently allocated to this subuser, in gigabytes.","type":"number","format":"float"},"traffic_used":{"description":"Traffic already consumed by this subuser, in gigabytes.","type":"number","format":"float"}},"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"}},"GetSubuserActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"subuser_hash":{"type":"array","items":{"type":"string","enum":["The subuser hash field is required.","The subuser hash must be 26 characters.","The selected subuser hash is invalid."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers/{residential_subuser}":{"get":{"tags":["residential-subusers"],"summary":"Get a residential subuser","description":"Returns a single residential subuser owned by the account.","operationId":"getResidentialSubuser","parameters":[{"name":"residential_subuser","in":"path","description":"Subuser hash. 26 characters.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Residential subuser details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialSubuserResource"}}}},"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":"Subuser not found or the residential user record does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"422":{"description":"Subuser hash failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubuserActionValidationError"}}}},"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"}}}}}}}}}
```

## Update a residential subuser

> Updates a subuser's username, password, and/or traffic allocation. Setting \`traffic\` transfers the delta to or from the main account's balance.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"UpdateSubuserRequest":{"title":"Update Subuser Request","description":"Payload for updating a residential subuser. At least one field must differ from the subuser's current state; sending unchanged values triggers a \"nothing to update\" error.","properties":{"username":{"description":"New subuser username. 3-30 alphanumeric or underscore characters.","type":["string","null"]},"password":{"description":"New subuser password. 6-16 alphanumeric characters.","type":["string","null"]},"traffic":{"description":"Total traffic the subuser should have available, in gigabytes. The server calculates the delta against the current allocation and transfers it between the reseller and the subuser accordingly.","type":["number","null"],"format":"float"}},"type":"object"},"ResidentialSubuserResource":{"title":"Residential Subuser Resource","description":"A residential subuser owned by the account.","required":["id","hash","username","password","traffic_available","traffic_used"],"properties":{"id":{"description":"Internal subuser identifier.","type":"integer"},"hash":{"description":"Subuser hash used to reference the subuser in API requests.","type":"string"},"username":{"description":"Subuser proxy username.","type":"string"},"password":{"description":"Subuser proxy password.","type":"string"},"traffic_available":{"description":"Traffic currently allocated to this subuser, in gigabytes.","type":"number","format":"float"},"traffic_used":{"description":"Traffic already consumed by this subuser, in gigabytes.","type":"number","format":"float"}},"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"}},"UpdateSubuserActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"subuser_hash":{"type":"array","items":{"type":"string","enum":["The subuser hash field is required.","The subuser hash must be 26 characters.","The selected subuser hash is invalid."]}},"username":{"type":"array","items":{"type":"string","enum":["The username must be a string.","The username format is invalid.","The username must be at least 3 characters.","The username must not be greater than 30 characters."]}},"password":{"type":"array","items":{"type":"string","enum":["The password must be a string.","The password must only contain letters and numbers.","The password must be at least 6 characters.","The password must not be greater than 16 characters."]}},"traffic":{"type":"array","items":{"type":"string","enum":["The traffic must be a number.","The traffic must be at least 0."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers/{residential_subuser}":{"put":{"tags":["residential-subusers"],"summary":"Update a residential subuser","description":"Updates a subuser's username, password, and/or traffic allocation. Setting `traffic` transfers the delta to or from the main account's balance.","operationId":"updateResidentialSubuser","parameters":[{"name":"residential_subuser","in":"path","description":"Subuser hash. 26 characters.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubuserRequest"}}}},"responses":{"200":{"description":"Updated subuser","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialSubuserResource"}}}},"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":"Subuser not found or the residential user record does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"409":{"description":"Nothing to update, username already taken, or the reseller does not have enough traffic to cover the requested increase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelopeDTO"}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubuserActionValidationError"}}}},"423":{"description":"A traffic-mutating operation is already in progress 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"}}}}}}}}}
```

## Delete a residential subuser

> Deletes a subuser. Any remaining traffic allocation on the subuser is transferred back to the main account's balance before deletion.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"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"}},"DeleteSubuserActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"subuser_hash":{"type":"array","items":{"type":"string","enum":["The subuser hash field is required.","The subuser hash must be 26 characters.","The selected subuser hash is invalid."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers/{residential_subuser}":{"delete":{"tags":["residential-subusers"],"summary":"Delete a residential subuser","description":"Deletes a subuser. Any remaining traffic allocation on the subuser is transferred back to the main account's balance before deletion.","operationId":"deleteResidentialSubuser","parameters":[{"name":"residential_subuser","in":"path","description":"Subuser hash. 26 characters.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Subuser deleted"},"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":"Subuser not found or the residential user record does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"422":{"description":"Subuser hash failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSubuserActionValidationError"}}}},"423":{"description":"A traffic-mutating operation is already in progress 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"}}}}}}}}}
```

## Give traffic to a residential subuser

> Transfers the requested amount of traffic from the main account's balance to the subuser.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"TransferTrafficRequest":{"title":"Transfer Traffic Request","description":"Payload for transferring traffic to or from a subuser.","required":["amount"],"properties":{"amount":{"description":"Amount of traffic to transfer, in gigabytes. Must be greater than 0.","type":"number","format":"float"}},"type":"object"},"ResidentialSubuserResource":{"title":"Residential Subuser Resource","description":"A residential subuser owned by the account.","required":["id","hash","username","password","traffic_available","traffic_used"],"properties":{"id":{"description":"Internal subuser identifier.","type":"integer"},"hash":{"description":"Subuser hash used to reference the subuser in API requests.","type":"string"},"username":{"description":"Subuser proxy username.","type":"string"},"password":{"description":"Subuser proxy password.","type":"string"},"traffic_available":{"description":"Traffic currently allocated to this subuser, in gigabytes.","type":"number","format":"float"},"traffic_used":{"description":"Traffic already consumed by this subuser, in gigabytes.","type":"number","format":"float"}},"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"}},"GiveTrafficActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"subuser_hash":{"type":"array","items":{"type":"string","enum":["The subuser hash field is required.","The subuser hash must be 26 characters.","The selected subuser hash is invalid."]}},"amount":{"type":"array","items":{"type":"string","enum":["The amount field is required.","The amount must be a number.","The amount must be greater than 0."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers/{residential_subuser}/give-traffic":{"post":{"tags":["residential-subusers"],"summary":"Give traffic to a residential subuser","description":"Transfers the requested amount of traffic from the main account's balance to the subuser.","operationId":"giveTrafficToResidentialSubuser","parameters":[{"name":"residential_subuser","in":"path","description":"Subuser hash. 26 characters.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferTrafficRequest"}}}},"responses":{"200":{"description":"Subuser with the updated traffic balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialSubuserResource"}}}},"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":"Subuser not found or the residential user record does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"409":{"description":"Account does not have enough traffic to transfer the requested amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelopeDTO"}}}},"422":{"description":"Request body or subuser hash failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiveTrafficActionValidationError"}}}},"423":{"description":"A traffic-mutating operation is already in progress 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"}}}}}}}}}
```

## Take traffic from a residential subuser

> Transfers the requested amount of traffic from the subuser back to the main account's balance.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-subusers","description":"Residential sub-user management — create, list, update, delete, traffic transfers"}],"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":{"TransferTrafficRequest":{"title":"Transfer Traffic Request","description":"Payload for transferring traffic to or from a subuser.","required":["amount"],"properties":{"amount":{"description":"Amount of traffic to transfer, in gigabytes. Must be greater than 0.","type":"number","format":"float"}},"type":"object"},"ResidentialSubuserResource":{"title":"Residential Subuser Resource","description":"A residential subuser owned by the account.","required":["id","hash","username","password","traffic_available","traffic_used"],"properties":{"id":{"description":"Internal subuser identifier.","type":"integer"},"hash":{"description":"Subuser hash used to reference the subuser in API requests.","type":"string"},"username":{"description":"Subuser proxy username.","type":"string"},"password":{"description":"Subuser proxy password.","type":"string"},"traffic_available":{"description":"Traffic currently allocated to this subuser, in gigabytes.","type":"number","format":"float"},"traffic_used":{"description":"Traffic already consumed by this subuser, in gigabytes.","type":"number","format":"float"}},"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"}},"TakeTrafficActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"subuser_hash":{"type":"array","items":{"type":"string","enum":["The subuser hash field is required.","The subuser hash must be 26 characters.","The selected subuser hash is invalid."]}},"amount":{"type":"array","items":{"type":"string","enum":["The amount field is required.","The amount must be a number.","The amount must be greater than 0."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/subusers/{residential_subuser}/take-traffic":{"post":{"tags":["residential-subusers"],"summary":"Take traffic from a residential subuser","description":"Transfers the requested amount of traffic from the subuser back to the main account's balance.","operationId":"takeTrafficFromResidentialSubuser","parameters":[{"name":"residential_subuser","in":"path","description":"Subuser hash. 26 characters.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferTrafficRequest"}}}},"responses":{"200":{"description":"Subuser with the updated traffic balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialSubuserResource"}}}},"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":"Subuser not found or the residential user record does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"409":{"description":"Subuser does not have enough traffic to transfer the requested amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelopeDTO"}}}},"422":{"description":"Request body or subuser hash failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeTrafficActionValidationError"}}}},"423":{"description":"A traffic-mutating operation is already in progress 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"}}}}}}}}}
```


# Orders

Residential order management — list, show, create, calculate pricing

## Calculate pricing for a residential order

> Returns the total price for a residential order of the given quantity, optionally applying a coupon. Does not create the order.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"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":{"CalculateResidentialOrderPricingResponse":{"title":"Calculate Residential Order Pricing Response","description":"Total price for the requested residential traffic quantity, optionally discounted by coupon.","required":["total"],"properties":{"total":{"description":"Calculated total price in USD.","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"}},"CalculateResidentialOrderPricingActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"quantity":{"type":"array","items":{"type":"string","enum":["The quantity field is required.","The quantity must be an integer.","The quantity must be at least 1."]}},"coupon_code":{"type":"array","items":{"type":"string","enum":["The coupon code must be a string."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/orders/calculate-pricing":{"get":{"tags":["residential-orders"],"summary":"Calculate pricing for a residential order","description":"Returns the total price for a residential order of the given quantity, optionally applying a coupon. Does not create the order.","operationId":"calculateResidentialOrderPricing","parameters":[{"name":"quantity","in":"query","description":"Amount of residential traffic to price, in gigabytes.","required":true,"schema":{"type":"integer"}},{"name":"coupon_code","in":"query","description":"Optional coupon code to apply to the calculation.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Calculated pricing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResidentialOrderPricingResponse"}}}},"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"}}}},"422":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResidentialOrderPricingActionValidationError"}}}},"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 orders

> Returns a paginated list of residential orders for the account.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"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":{"ResidentialOrderCollection":{"title":"Residential Order Collection","description":"Paginated list of residential orders.","required":["data","meta"],"properties":{"data":{"description":"Orders on the current page.","type":"array","items":{"$ref":"#/components/schemas/ResidentialOrderResource"}},"meta":{"description":"Pagination metadata.","required":["current_page","last_page","per_page","total"],"properties":{"current_page":{"description":"Current page number.","type":"integer"},"last_page":{"description":"Last available page number.","type":"integer"},"per_page":{"description":"Number of items per page.","type":"integer"},"total":{"description":"Total number of orders across all pages.","type":"integer"}},"type":"object"}},"type":"object"},"ResidentialOrderResource":{"title":"Residential Order Resource","description":"A single residential order.","required":["id","product_name","status","amount","quantity","created_at"],"properties":{"id":{"description":"Unique order identifier.","type":"integer"},"product_name":{"description":"Name of the product.","type":"string"},"status":{"description":"Order lifecycle status.","type":"string","enum":["unpaid","in-progress","confirmed","refunded","expired","paid","payment_hold","canceled"]},"amount":{"description":"Order amount charged, in USD.","type":"number","format":"float"},"quantity":{"description":"Amount of residential traffic, in gigabytes.","type":"number","format":"float"},"created_at":{"description":"Timestamp when the order was created.","type":"string","format":"date-time"}},"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"}},"GetResidentialOrdersActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"page":{"type":"array","items":{"type":"string","enum":["The page must be an integer.","The page must be at least 1.","The page must not be greater than 10000."]}},"per_page":{"type":"array","items":{"type":"string","enum":["The per page must be an integer.","The per page must be at least 1.","The per page must not be greater than 100."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/orders":{"get":{"tags":["residential-orders"],"summary":"List residential orders","description":"Returns a paginated list of residential orders for the account.","operationId":"getResidentialOrders","parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Number of orders per page (1-100). Defaults to 20.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated residential orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderCollection"}}}},"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"}}}},"422":{"description":"Pagination parameters failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResidentialOrdersActionValidationError"}}}},"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"}}}}}}}}}
```

## Create a residential order

> Purchases a residential order for the account. Payment is made either from the account balance or from a saved card when \`card\_id\` is supplied.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"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":{"CreateResidentialOrderRequest":{"title":"Create Residential Order Request","description":"Payload for purchasing a residential order.","required":["quantity"],"properties":{"quantity":{"description":"Amount of residential traffic to purchase, in gigabytes.","type":"integer"},"coupon_code":{"description":"Optional coupon code to apply to the order for a discount.","type":["string","null"]},"card_id":{"description":"Optional saved card identifier to charge. Omit to charge the account balance.","type":["integer","null"]}},"type":"object"},"ResidentialOrderResource":{"title":"Residential Order Resource","description":"A single residential order.","required":["id","product_name","status","amount","quantity","created_at"],"properties":{"id":{"description":"Unique order identifier.","type":"integer"},"product_name":{"description":"Name of the product.","type":"string"},"status":{"description":"Order lifecycle status.","type":"string","enum":["unpaid","in-progress","confirmed","refunded","expired","paid","payment_hold","canceled"]},"amount":{"description":"Order amount charged, in USD.","type":"number","format":"float"},"quantity":{"description":"Amount of residential traffic, in gigabytes.","type":"number","format":"float"},"created_at":{"description":"Timestamp when the order was created.","type":"string","format":"date-time"}},"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"}},"CreateResidentialOrderActionValidationError":{"required":["error"],"properties":{"error":{"required":["code","message","detailed_messages"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"detailed_messages":{"properties":{"quantity":{"type":"array","items":{"type":"string","enum":["The quantity field is required.","The quantity must be an integer.","The quantity must be at least 1."]}},"coupon_code":{"type":"array","items":{"type":"string","enum":["The coupon code must be a string."]}},"card_id":{"type":"array","items":{"type":"string","enum":["The card id must be an integer."]}}},"type":"object"}},"type":"object"}},"type":"object"}}},"paths":{"/v1/residential/orders":{"post":{"tags":["residential-orders"],"summary":"Create a residential order","description":"Purchases a residential order for the account. Payment is made either from the account balance or from a saved card when `card_id` is supplied.","operationId":"createResidentialOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResidentialOrderRequest"}}}},"responses":{"200":{"description":"Created residential order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResource"}}}},"401":{"description":"Missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDTO"}}}},"402":{"description":"Account balance is not sufficient to complete the order","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"}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResidentialOrderActionValidationError"}}}},"423":{"description":"Another order for this account is currently being processed","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"}}}}}}}}}
```

## Get a residential order

> Returns a single residential order owned by the account.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"residential-orders","description":"Residential order management — list, show, create, calculate pricing"}],"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":{"ResidentialOrderResource":{"title":"Residential Order Resource","description":"A single residential order.","required":["id","product_name","status","amount","quantity","created_at"],"properties":{"id":{"description":"Unique order identifier.","type":"integer"},"product_name":{"description":"Name of the product.","type":"string"},"status":{"description":"Order lifecycle status.","type":"string","enum":["unpaid","in-progress","confirmed","refunded","expired","paid","payment_hold","canceled"]},"amount":{"description":"Order amount charged, in USD.","type":"number","format":"float"},"quantity":{"description":"Amount of residential traffic, in gigabytes.","type":"number","format":"float"},"created_at":{"description":"Timestamp when the order was created.","type":"string","format":"date-time"}},"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/orders/{order}":{"get":{"tags":["residential-orders"],"summary":"Get a residential order","description":"Returns a single residential order owned by the account.","operationId":"getResidentialOrder","parameters":[{"name":"order","in":"path","description":"Residential order identifier.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Residential order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResource"}}}},"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":"Order not found or the residential user record does not exist","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"}}}}}}}}}
```


# 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"}}}}}}}}}
```


# Cards

Payment cards on the account

## List user payment cards

> Returns the list of active payment cards on the account.

```json
{"openapi":"3.1.0","info":{"title":"MarsProxies Residential API documentation","version":"1.0.0"},"tags":[{"name":"cards","description":"Payment cards on the account"}],"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":{"CardCollection":{"title":"Card Collection","description":"List of active payment cards on the account.","required":["data"],"properties":{"data":{"description":"Cards on the account, with the default card listed first.","type":"array","items":{"$ref":"#/components/schemas/CardResource"}}},"type":"object"},"CardResource":{"title":"Card Resource","description":"A single payment card on the account.","required":["id","provider","custom_name","default","payment_method","card_type","currency","last_four_digits","expiry_date"],"properties":{"id":{"description":"Unique card identifier.","type":"integer"},"provider":{"description":"Payment provider that issued the card token.","type":"string"},"custom_name":{"description":"User-provided friendly name for the card.","type":["string","null"]},"default":{"description":"Whether this card is the default payment method.","type":"boolean"},"payment_method":{"description":"Payment method type.","type":"string"},"card_type":{"description":"Card brand reported by the provider.","type":["string","null"]},"currency":{"description":"Card currency.","type":["string","null"]},"last_four_digits":{"description":"Last four digits of the card number.","type":["string","null"]},"expiry_date":{"description":"Card expiry date.","type":["string","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"}}}},"paths":{"/v1/cards":{"get":{"tags":["cards"],"summary":"List user payment cards","description":"Returns the list of active payment cards on the account.","operationId":"getCards","responses":{"200":{"description":"Active payment cards","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCollection"}}}},"401":{"description":"Missing or invalid API token","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"}}}}}}}}}
```