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

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