Residential sub-users and traffic

Use one parent API token to manage residential sub-users belonging to your account. Each sub-user has its own proxy credentials and traffic allocation. The examples use API v2.

Prepare API requests

Use your API token in the Authorization: Bearer header for every management request. Set LTESOCKS_API_TOKEN in your environment. Requests use your account automatically; do not send parent_id.

API_URL='https://api.ltesocks.io/v2'

curl "$API_URL/user" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

curl "$API_URL/proxies/residential?page=1&page_size=20" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

Read residentialProxy.availableData from GET /user for the account’s remaining residential traffic in bytes. Offer traffic_limit values are in MB, and prices are in USD cents. Sub-user fields traffic_bytes, used_bytes, and remaining_bytes are integer bytes: 1073741824 bytes = 1 GiB.

Purchase data for the account

Select an offer from data: set TARIFF_ID to its id, TARIFF_OPTION_ID to the chosen option’s id, and PRICE_HASH to that option’s current price_hash. Review final_price before purchasing. Set PURCHASE_KEY to a new UUID and retain it with the request body.

curl -X POST "$API_URL/proxies/residential" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${PURCHASE_KEY}" \
  --data "{\"tariff_id\":${TARIFF_ID},\"tariff_option_id\":${TARIFF_OPTION_ID},\"price_hash\":\"${PRICE_HASH}\"}"

On 409 with error_code=priceChanged, fetch offers again and confirm the new price before submitting a new purchase. After a timeout, reuse the original key and body. An uncertain 500 may be retained for 24 hours: reconcile the purchase before attempting another payment. Read /user again to check the result. See residential packages and purchase data.

Create a sub-user

Set CREATE_KEY to a new UUID for this creation. Send only the login suffix: customer_01 becomes {parent_login}_customer_01. The suffix accepts ASCII letters, digits, underscores and hyphens, with 4–50 characters; the full login must fit within 64 characters. Email is generated automatically. Omit email, first_name, and last_name.

POST/proxies/residential/subusersCreate sub-user

curl -X POST "$API_URL/proxies/residential/subusers" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${CREATE_KEY}" \
  --data '{"login":"customer_01","traffic_bytes":1073741824}'

Provide a positive integer traffic_bytes, up to 109951162777600 bytes (100 TiB). Creation and increases are subject to the account’s available allocation and the sub-user’s total quota. The active package is selected by default; optional package_id must identify that configured package. Example response, shortened:

{
  "success": true,
  "code": 201,
  "data": {
    "id": "e8b6be73-fc1e-4f06-8a3d-b16207b30ec5",
    "login": "parent_customer_01",
    "traffic_bytes": 1073741824,
    "used_bytes": 0,
    "remaining_bytes": 1073741824
  }
}

Save the returned data.id as CHILD_ID; replace the illustrative UUID below with that value. Every subsequent request remains scoped to the authenticated parent.

List and inspect sub-users

GET/proxies/residential/subusersList sub-users

curl --get "$API_URL/proxies/residential/subusers" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=10'

Use page starting at 1. Each page contains up to 10 sub-users; page_size accepts only 10. Read page_info.page, page_info.page_size, and page_info.total_count to continue paging. Supplying either parameter enables pagination; page_size=10 alone selects page 1. Omit both parameters to get the full list without page_info. This endpoint does not support a search query.

GET/proxies/residential/subusers/{childId}Inspect sub-user

CHILD_ID='e8b6be73-fc1e-4f06-8a3d-b16207b30ec5'

curl "$API_URL/proxies/residential/subusers/$CHILD_ID" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

curl "$API_URL/proxies/residential/subusers/$CHILD_ID/package" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

GET/proxies/residential/subusers/{childId}/packageRead traffic counters

GET /proxies/residential/subusers/{childId}/package returns id, package_id, traffic_bytes (allocated quota), used_bytes (consumed traffic), and remaining_bytes (remaining traffic) inside data.

Get connection credentials

GET/proxies/residential/subusers/{childId}/credentialsGet proxy credentials

curl "$API_URL/proxies/residential/subusers/$CHILD_ID/credentials" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}"

Use data.username and data.password exactly as returned to authenticate proxy connections. The connection username is package-based and can differ from the sub-user login. The bearer token authenticates management requests. Example response:

{
  "success": true,
  "code": 200,
  "data": {
    "username": "product_residential",
    "password": "<sub-user-package-password>"
  }
}

Keep the returned password out of application logs. For country, region, city and ASN selection, see Residential targeting.

Change the traffic allocation

Create a separate UUID for each intended mutation (ADD_KEY, SUBTRACT_KEY, RESET_KEY). Keep the same key and body for retries of that mutation. Add 512 MiB:

POST/proxies/residential/subusers/{childId}/traffic/{action}Manage traffic

curl -X POST "$API_URL/proxies/residential/subusers/$CHILD_ID/traffic/add" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${ADD_KEY}" \
  --data '{"traffic_bytes":536870912}'

Subtract 256 MiB. The amount must be positive and cannot exceed remaining_bytes:

curl -X POST "$API_URL/proxies/residential/subusers/$CHILD_ID/traffic/subtract" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${SUBTRACT_KEY}" \
  --data '{"traffic_bytes":268435456}'

Reset the sub-user’s remaining data without sending traffic_bytes:

curl -X POST "$API_URL/proxies/residential/subusers/$CHILD_ID/traffic/reset" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H "Idempotency-Key: ${RESET_KEY}"

Inspect the returned traffic counters and read /package again to verify the result. add cannot exceed available account allocation or the total quota of 109951162777600 bytes. Quota violations return 422; an unsupported action returns 404.

Delete a sub-user

Stop traffic using the child’s credentials, verify CHILD_ID, and set a new DELETE_KEY. Deletion removes the sub-user; repeat an uncertain request with the same key.

DELETE/proxies/residential/subusers/{childId}Delete sub-user

curl -X DELETE "$API_URL/proxies/residential/subusers/$CHILD_ID" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H "Idempotency-Key: ${DELETE_KEY}"

Successful deletion returns HTTP 200 with an empty data array:

{ "success": true, "code": 200, "data": [] }

Handle failures and retries

Treat 401 as an authentication failure and check your API token. For 403, confirm that you are using the account that owns the sub-user; contact support if access is still denied. For 404, check CHILD_ID and the traffic action in the URL. For 409, inspect message before retrying a conflicting operation. For 422, inspect message and any field errors: check the request key, amounts, available traffic, and supported fields. After 429, wait before retrying. After a timeout or a 500, 502, or 503 response, retain the original key, inspect current state, and retry the same mutation with the same body. See Idempotency and safe retries.

The API Reference is generated from the published v2 contract.