Sub-users

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

List residential subusers

get

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

Authorizations

AuthorizationstringRequired

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

Query parameters

pageintegerOptional

Page number to fetch. Defaults to 1.

Example: 1

per_pageintegerOptional

Number of subusers per page.

Example: 20

searchstringOptional

Filter by subuser username (partial match) or exact internal id. 1-30 characters.

Example: mr1234

Responses

200

Paginated residential subusers

application/json

Paginated list of residential subusers.

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Residential user record not found for this account

application/json

422

Pagination or search parameters failed validation

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

get/v1/residential/subusers

curl --request GET \
  --url 'https://api.marsproxies.com/v1/residential/subusers?page=1&per_page=20&search=mr1234' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

{
  "data": [
    {
      "id": 42,
      "hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
      "username": "mr12345ab1c",
      "password": "Maf83Kz7k2",
      "traffic_available": 2.5,
      "traffic_used": 1.28
    }
  ]
}

Create a residential subuser

post

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.

Authorizations

AuthorizationstringRequired

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

Body

Payload for creating a residential subuser. All fields are optional — server generates a random username and password when omitted.

usernamestring · nullableOptional

Desired subuser username. 3-30 alphanumeric or underscore characters.

Example: mr12345ab1c

passwordstring · nullableOptional

Desired subuser password. 6-16 alphanumeric characters.

Example: Maf83Kz7k2

trafficnumber · nullableOptional

Initial traffic to allocate to the subuser, in gigabytes. Must not exceed the main account's available traffic.

Example: 2.5

Responses

200

Newly created subuser

application/json

A residential subuser owned by the account.

idintegerRequired

Internal subuser identifier.

Example: 42

hashstringRequired

Subuser hash used to reference the subuser in API requests.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

usernamestringRequired

Subuser proxy username.

Example: mr12345ab1c

passwordstringRequired

Subuser proxy password.

Example: Maf83Kz7k2

traffic_availablenumber · floatRequired

Traffic currently allocated to this subuser, in gigabytes.

Example: 2.5

traffic_usednumber · floatRequired

Traffic already consumed by this subuser, in gigabytes.

Example: 1.28

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Residential user record not found for this account

application/json

409

Username is already taken, or the main account does not have enough traffic to allocate to the new subuser

application/json

422

Request body validation failed

application/json

423

A traffic-mutating operation is already in progress for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

post/v1/residential/subusers

curl --request POST \
  --url https://api.marsproxies.com/v1/residential/subusers \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"username":"mr12345ab1c","password":"Maf83Kz7k2","traffic":2.5}'

{
  "id": 42,
  "hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "username": "mr12345ab1c",
  "password": "Maf83Kz7k2",
  "traffic_available": 2.5,
  "traffic_used": 1.28
}

Get a residential subuser

get

Returns a single residential subuser owned by the account.

Authorizations

AuthorizationstringRequired

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

Path parameters

residential_subuserstringRequired

Subuser hash. 26 characters.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

Responses

200

Residential subuser details

application/json

A residential subuser owned by the account.

idintegerRequired

Internal subuser identifier.

Example: 42

hashstringRequired

Subuser hash used to reference the subuser in API requests.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

usernamestringRequired

Subuser proxy username.

Example: mr12345ab1c

passwordstringRequired

Subuser proxy password.

Example: Maf83Kz7k2

traffic_availablenumber · floatRequired

Traffic currently allocated to this subuser, in gigabytes.

Example: 2.5

traffic_usednumber · floatRequired

Traffic already consumed by this subuser, in gigabytes.

Example: 1.28

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Subuser not found or the residential user record does not exist

application/json

422

Subuser hash failed validation

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

get/v1/residential/subusers/{residential_subuser}

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

{
  "id": 42,
  "hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "username": "mr12345ab1c",
  "password": "Maf83Kz7k2",
  "traffic_available": 2.5,
  "traffic_used": 1.28
}

Update a residential subuser

put

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

Authorizations

AuthorizationstringRequired

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

Path parameters

residential_subuserstringRequired

Subuser hash. 26 characters.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

Body

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.

usernamestring · nullableOptional

New subuser username. 3-30 alphanumeric or underscore characters.

Example: mr12345ab1c

passwordstring · nullableOptional

New subuser password. 6-16 alphanumeric characters.

Example: NewMp83Kz7

trafficnumber · nullableOptional

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.

Example: 5

Responses

200

Updated subuser

application/json

A residential subuser owned by the account.

idintegerRequired

Internal subuser identifier.

Example: 42

hashstringRequired

Subuser hash used to reference the subuser in API requests.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

usernamestringRequired

Subuser proxy username.

Example: mr12345ab1c

passwordstringRequired

Subuser proxy password.

Example: Maf83Kz7k2

traffic_availablenumber · floatRequired

Traffic currently allocated to this subuser, in gigabytes.

Example: 2.5

traffic_usednumber · floatRequired

Traffic already consumed by this subuser, in gigabytes.

Example: 1.28

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Subuser not found or the residential user record does not exist

application/json

409

Nothing to update, username already taken, or the reseller does not have enough traffic to cover the requested increase.

application/json

422

Request body validation failed

application/json

423

A traffic-mutating operation is already in progress for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

put/v1/residential/subusers/{residential_subuser}

curl --request PUT \
  --url https://api.marsproxies.com/v1/residential/subusers/A1B2C3D4E5F6G7H8I9J0K1L2M3 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"username":"mr12345ab1c","password":"NewMp83Kz7","traffic":5}'

{
  "id": 42,
  "hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "username": "mr12345ab1c",
  "password": "Maf83Kz7k2",
  "traffic_available": 2.5,
  "traffic_used": 1.28
}

Delete a residential subuser

delete

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

Authorizations

AuthorizationstringRequired

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

Path parameters

residential_subuserstringRequired

Subuser hash. 26 characters.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

Responses

204

Subuser deleted

No content

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Subuser not found or the residential user record does not exist

application/json

422

Subuser hash failed validation

application/json

423

A traffic-mutating operation is already in progress for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

delete/v1/residential/subusers/{residential_subuser}

curl --request DELETE \
  --url https://api.marsproxies.com/v1/residential/subusers/A1B2C3D4E5F6G7H8I9J0K1L2M3 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

No content

Give traffic to a residential subuser

post

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

Authorizations

AuthorizationstringRequired

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

Path parameters

residential_subuserstringRequired

Subuser hash. 26 characters.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

Body

Payload for transferring traffic to or from a subuser.

amountnumber · floatRequired

Amount of traffic to transfer, in gigabytes. Must be greater than 0.

Example: 1.25

Responses

200

Subuser with the updated traffic balance

application/json

A residential subuser owned by the account.

idintegerRequired

Internal subuser identifier.

Example: 42

hashstringRequired

Subuser hash used to reference the subuser in API requests.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

usernamestringRequired

Subuser proxy username.

Example: mr12345ab1c

passwordstringRequired

Subuser proxy password.

Example: Maf83Kz7k2

traffic_availablenumber · floatRequired

Traffic currently allocated to this subuser, in gigabytes.

Example: 2.5

traffic_usednumber · floatRequired

Traffic already consumed by this subuser, in gigabytes.

Example: 1.28

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Subuser not found or the residential user record does not exist

application/json

409

Account does not have enough traffic to transfer the requested amount

application/json

422

Request body or subuser hash failed validation

application/json

423

A traffic-mutating operation is already in progress for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

post/v1/residential/subusers/{residential_subuser}/give-traffic

curl --request POST \
  --url https://api.marsproxies.com/v1/residential/subusers/A1B2C3D4E5F6G7H8I9J0K1L2M3/give-traffic \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"amount":1.25}'

{
  "id": 42,
  "hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "username": "mr12345ab1c",
  "password": "Maf83Kz7k2",
  "traffic_available": 2.5,
  "traffic_used": 1.28
}

Take traffic from a residential subuser

post

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

Authorizations

AuthorizationstringRequired

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

Path parameters

residential_subuserstringRequired

Subuser hash. 26 characters.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

Body

Payload for transferring traffic to or from a subuser.

amountnumber · floatRequired

Amount of traffic to transfer, in gigabytes. Must be greater than 0.

Example: 1.25

Responses

200

Subuser with the updated traffic balance

application/json

A residential subuser owned by the account.

idintegerRequired

Internal subuser identifier.

Example: 42

hashstringRequired

Subuser hash used to reference the subuser in API requests.

Example: A1B2C3D4E5F6G7H8I9J0K1L2M3

usernamestringRequired

Subuser proxy username.

Example: mr12345ab1c

passwordstringRequired

Subuser proxy password.

Example: Maf83Kz7k2

traffic_availablenumber · floatRequired

Traffic currently allocated to this subuser, in gigabytes.

Example: 2.5

traffic_usednumber · floatRequired

Traffic already consumed by this subuser, in gigabytes.

Example: 1.28

401

Missing or invalid API token

application/json

403

Residential API is not enabled for this account

application/json

404

Subuser not found or the residential user record does not exist

application/json

409

Subuser does not have enough traffic to transfer the requested amount

application/json

422

Request body or subuser hash failed validation

application/json

423

A traffic-mutating operation is already in progress for this account

application/json

429

Rate limit exceeded

application/json

500

Unknown error

application/json

post/v1/residential/subusers/{residential_subuser}/take-traffic

curl --request POST \
  --url https://api.marsproxies.com/v1/residential/subusers/A1B2C3D4E5F6G7H8I9J0K1L2M3/take-traffic \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"amount":1.25}'

{
  "id": 42,
  "hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "username": "mr12345ab1c",
  "password": "Maf83Kz7k2",
  "traffic_available": 2.5,
  "traffic_used": 1.28
}

PreviousAccount NextOrders

Last updated 1 month ago

Was this helpful?