# Sub Users

Sub-user management endpoints

## List all sub-users

> Returns a paginated list of sub-users for the authenticated user. Supports filtering by type and status.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"SubUser":{"title":"Sub-User","description":"A sub-user represents a proxy credential that can be used for authentication. Sub-users are associated with different proxy types (datacenter, residential, ISP, IPv6) and have their own bandwidth allocations and settings.","required":["uuid","name","type","status","created_at","updated_at"],"properties":{"uuid":{"description":"Unique identifier for the sub-user. Use this UUID in all API operations.","type":"string","format":"uuid"},"name":{"description":"Username for proxy authentication. This is the login credential used when connecting to the proxy server.","type":"string"},"type":{"description":"Proxy product type. Determines the IP pool and features available.","type":"string","enum":["datacenter","residential","ipv6","isp"]},"status":{"description":"Current status of the sub-user. Only \"active\" sub-users can be used for proxy connections.","type":"string","enum":["active","expired","suspended"]},"expires_at":{"description":"Expiration date/time in ISO 8601 format. Null for sub-users with no expiration. After expiration, status changes to \"expired\".","type":"string","format":"date-time","nullable":true},"created_at":{"description":"Creation timestamp in ISO 8601 format.","type":"string","format":"date-time"},"updated_at":{"description":"Last update timestamp in ISO 8601 format.","type":"string","format":"date-time"},"credentials":{"description":"Proxy authentication credentials. Only included when `include=credentials` is specified.","properties":{"username":{"description":"Proxy authentication username.","type":"string"},"password":{"description":"Proxy authentication password.","type":"string"}},"type":"object","nullable":true},"traffic":{"description":"Bandwidth usage information. Only included when `include=traffic` is specified.","properties":{"used":{"description":"Bandwidth used in GB.","type":"number","format":"float"},"total":{"description":"Total bandwidth allocation in GB.","type":"number","format":"float"},"remaining":{"description":"Remaining bandwidth in GB.","type":"number","format":"float"},"unit":{"description":"Unit of measurement.","type":"string"}},"type":"object","nullable":true},"proxy_settings":{"description":"Advanced proxy settings. Only included when `include=proxy_settings` is specified.","properties":{"whitelisted_ips":{"description":"Allowed IP addresses.","type":"array","items":{"type":"string"}},"country_list":{"description":"Country distribution for datacenter/ISP.","type":"object"},"high_priority":{"description":"High priority routing enabled.","type":"boolean"},"high_concurrency":{"description":"High concurrency mode enabled.","type":"boolean"},"purchased_ip_count":{"description":"Number of IPs purchased.","type":"integer","nullable":true}},"type":"object","nullable":true},"ip_list":{"description":"List of assigned proxy IPs. Only available for ISP and Datacenter sub-users. Included when `include=ip_list` is specified.","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"},"PaginationMeta":{"title":"Pagination Metadata","description":"Standard pagination information included with all paginated list responses","required":["current_page","last_page","per_page","total"],"properties":{"current_page":{"type":"integer","minimum":1},"last_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","maximum":100,"minimum":1},"total":{"type":"integer","minimum":0},"from":{"type":"integer","nullable":true},"to":{"type":"integer","nullable":true}},"type":"object"}}},"paths":{"/sub-users":{"get":{"tags":["Sub-Users"],"summary":"List all sub-users","description":"Returns a paginated list of sub-users for the authenticated user. Supports filtering by type and status.","operationId":"bec72fd518ae2381b52b1b4204204c99","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":15,"maximum":100}},{"name":"filter[type]","in":"query","description":"Filter by proxy type: datacenter, residential, ipv6, isp","schema":{"type":"string","enum":["datacenter","residential","ipv6","isp"]}},{"name":"filter[status]","in":"query","description":"Filter by status: active, expired","schema":{"type":"string","enum":["active","expired"]}},{"name":"include","in":"query","description":"Comma-separated list: credentials, traffic, proxy_settings, ip_list (ISP/Datacenter only)","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort field with direction (prefix with - for desc)","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SubUser"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"type":"object"}}}},"401":{"description":"Unauthorized"}}}}}}
```

## Create a new sub-user

> Creates a new sub-user (proxy credential). Requires an active reseller account with sufficient balance. The required fields vary by proxy type:\
> \
> \*\*Residential:\*\*\
> \- \`days\` (required): Duration in days\
> \- \`bandwidth\` (required): Bandwidth in GB (1-5000)\
> \
> \*\*Datacenter:\*\*\
> \- \`bandwidth\` (required): Bandwidth in GB or "unlimited"\
> \- \`ends\_at\` (required): End date (YYYY-MM-DD format)\
> \- \`num\_ips\` (optional): Number of IPs\
> \- \`country\_proxies\` (optional): Country distribution object\
> \
> \*\*ISP:\*\*\
> \- \`bandwidth\` (required): Bandwidth in GB or "unlimited"\
> \- \`ends\_at\` (required): End date (YYYY-MM-DD format)\
> \- \`num\_ips\` (optional): Number of IPs\
> \- \`country\_proxies\` (optional): Country distribution object\
> \
> \*\*IPv6:\*\*\
> \- \`days\` (optional): Duration in days\
> \- \`bandwidth\` (optional): Bandwidth in GB (0-5000)\
> \- \`connections\` (optional): Number of connections (min 500)\
> \- \`mbps\` (optional): Speed in Mbps

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"SubUserStoreRequest":{"required":["type"],"properties":{"name":{"description":"Username for the sub-user (12-16 alphanumeric characters). Optional - will be auto-generated if not provided.","type":"string","maxLength":16,"minLength":12},"type":{"description":"Proxy type","type":"string","enum":["datacenter","residential","ipv6","isp"]},"bandwidth":{"description":"Bandwidth allocation in GB. For datacenter/isp: use numeric value or \"unlimited\". For residential: required, 1-5000 GB. For ipv6: optional.","oneOf":[{"type":"number","format":"float","minimum":1},{"type":"string","enum":["unlimited"]}]},"days":{"description":"Duration in days (for residential/ipv6)","type":"integer","minimum":1},"ends_at":{"description":"End date for the subscription (for datacenter/isp). Format: YYYY-MM-DD","type":"string","format":"date"},"num_ips":{"description":"Number of IPs (for datacenter/ISP)","type":"integer","minimum":1},"whitelisted_ips":{"description":"Number of whitelisted IP slots. Defaults to 1. Each additional slot incurs a 10% surcharge. For datacenter/ISP only.","type":"integer","default":1,"minimum":1},"country_proxies":{"description":"Country distribution for IPs. Object with country codes as keys and IP counts as values. Example: {\"US\": 5, \"DE\": 3}","type":"object","additionalProperties":{"type":"integer"}},"high_priority":{"description":"Enable high priority (additional cost)","type":"boolean","default":false},"high_concurrency":{"description":"Enable high concurrency - 2500 threads (additional cost)","type":"boolean","default":false},"parent_sub_user_id":{"description":"Parent sub-user UUID for creating extra sub-users (residential only)","type":"string","format":"uuid"},"connections":{"description":"Number of connections (for ipv6)","type":"integer","minimum":500},"mbps":{"description":"Speed in Mbps (for ipv6 speed-based plans)","type":"integer","minimum":1},"plan_id":{"description":"IPv6 pricing plan ID","type":"string"}},"type":"object"},"SubUser":{"title":"Sub-User","description":"A sub-user represents a proxy credential that can be used for authentication. Sub-users are associated with different proxy types (datacenter, residential, ISP, IPv6) and have their own bandwidth allocations and settings.","required":["uuid","name","type","status","created_at","updated_at"],"properties":{"uuid":{"description":"Unique identifier for the sub-user. Use this UUID in all API operations.","type":"string","format":"uuid"},"name":{"description":"Username for proxy authentication. This is the login credential used when connecting to the proxy server.","type":"string"},"type":{"description":"Proxy product type. Determines the IP pool and features available.","type":"string","enum":["datacenter","residential","ipv6","isp"]},"status":{"description":"Current status of the sub-user. Only \"active\" sub-users can be used for proxy connections.","type":"string","enum":["active","expired","suspended"]},"expires_at":{"description":"Expiration date/time in ISO 8601 format. Null for sub-users with no expiration. After expiration, status changes to \"expired\".","type":"string","format":"date-time","nullable":true},"created_at":{"description":"Creation timestamp in ISO 8601 format.","type":"string","format":"date-time"},"updated_at":{"description":"Last update timestamp in ISO 8601 format.","type":"string","format":"date-time"},"credentials":{"description":"Proxy authentication credentials. Only included when `include=credentials` is specified.","properties":{"username":{"description":"Proxy authentication username.","type":"string"},"password":{"description":"Proxy authentication password.","type":"string"}},"type":"object","nullable":true},"traffic":{"description":"Bandwidth usage information. Only included when `include=traffic` is specified.","properties":{"used":{"description":"Bandwidth used in GB.","type":"number","format":"float"},"total":{"description":"Total bandwidth allocation in GB.","type":"number","format":"float"},"remaining":{"description":"Remaining bandwidth in GB.","type":"number","format":"float"},"unit":{"description":"Unit of measurement.","type":"string"}},"type":"object","nullable":true},"proxy_settings":{"description":"Advanced proxy settings. Only included when `include=proxy_settings` is specified.","properties":{"whitelisted_ips":{"description":"Allowed IP addresses.","type":"array","items":{"type":"string"}},"country_list":{"description":"Country distribution for datacenter/ISP.","type":"object"},"high_priority":{"description":"High priority routing enabled.","type":"boolean"},"high_concurrency":{"description":"High concurrency mode enabled.","type":"boolean"},"purchased_ip_count":{"description":"Number of IPs purchased.","type":"integer","nullable":true}},"type":"object","nullable":true},"ip_list":{"description":"List of assigned proxy IPs. Only available for ISP and Datacenter sub-users. Included when `include=ip_list` is specified.","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"}}},"paths":{"/sub-users":{"post":{"tags":["Sub-Users"],"summary":"Create a new sub-user","description":"Creates a new sub-user (proxy credential). Requires an active reseller account with sufficient balance. The required fields vary by proxy type:\n\n**Residential:**\n- `days` (required): Duration in days\n- `bandwidth` (required): Bandwidth in GB (1-5000)\n\n**Datacenter:**\n- `bandwidth` (required): Bandwidth in GB or \"unlimited\"\n- `ends_at` (required): End date (YYYY-MM-DD format)\n- `num_ips` (optional): Number of IPs\n- `country_proxies` (optional): Country distribution object\n\n**ISP:**\n- `bandwidth` (required): Bandwidth in GB or \"unlimited\"\n- `ends_at` (required): End date (YYYY-MM-DD format)\n- `num_ips` (optional): Number of IPs\n- `country_proxies` (optional): Country distribution object\n\n**IPv6:**\n- `days` (optional): Duration in days\n- `bandwidth` (optional): Bandwidth in GB (0-5000)\n- `connections` (optional): Number of connections (min 500)\n- `mbps` (optional): Speed in Mbps","operationId":"ac13af741df448c5c204d6d6347d2405","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserStoreRequest"}}}},"responses":{"201":{"description":"Sub-user created successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/SubUser"},"cost":{"description":"Cost deducted from reseller balance","type":"number","format":"float"}},"type":"object"}}}},"400":{"description":"Invalid request or insufficient balance","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"pay_url":{"description":"Invoice payment URL (only when balance is insufficient)","type":"string"}},"type":"object"}}}},"401":{"description":"Unauthorized"},"422":{"description":"Validation error"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Get sub-user details

> Returns detailed information about a specific sub-user.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"SubUser":{"title":"Sub-User","description":"A sub-user represents a proxy credential that can be used for authentication. Sub-users are associated with different proxy types (datacenter, residential, ISP, IPv6) and have their own bandwidth allocations and settings.","required":["uuid","name","type","status","created_at","updated_at"],"properties":{"uuid":{"description":"Unique identifier for the sub-user. Use this UUID in all API operations.","type":"string","format":"uuid"},"name":{"description":"Username for proxy authentication. This is the login credential used when connecting to the proxy server.","type":"string"},"type":{"description":"Proxy product type. Determines the IP pool and features available.","type":"string","enum":["datacenter","residential","ipv6","isp"]},"status":{"description":"Current status of the sub-user. Only \"active\" sub-users can be used for proxy connections.","type":"string","enum":["active","expired","suspended"]},"expires_at":{"description":"Expiration date/time in ISO 8601 format. Null for sub-users with no expiration. After expiration, status changes to \"expired\".","type":"string","format":"date-time","nullable":true},"created_at":{"description":"Creation timestamp in ISO 8601 format.","type":"string","format":"date-time"},"updated_at":{"description":"Last update timestamp in ISO 8601 format.","type":"string","format":"date-time"},"credentials":{"description":"Proxy authentication credentials. Only included when `include=credentials` is specified.","properties":{"username":{"description":"Proxy authentication username.","type":"string"},"password":{"description":"Proxy authentication password.","type":"string"}},"type":"object","nullable":true},"traffic":{"description":"Bandwidth usage information. Only included when `include=traffic` is specified.","properties":{"used":{"description":"Bandwidth used in GB.","type":"number","format":"float"},"total":{"description":"Total bandwidth allocation in GB.","type":"number","format":"float"},"remaining":{"description":"Remaining bandwidth in GB.","type":"number","format":"float"},"unit":{"description":"Unit of measurement.","type":"string"}},"type":"object","nullable":true},"proxy_settings":{"description":"Advanced proxy settings. Only included when `include=proxy_settings` is specified.","properties":{"whitelisted_ips":{"description":"Allowed IP addresses.","type":"array","items":{"type":"string"}},"country_list":{"description":"Country distribution for datacenter/ISP.","type":"object"},"high_priority":{"description":"High priority routing enabled.","type":"boolean"},"high_concurrency":{"description":"High concurrency mode enabled.","type":"boolean"},"purchased_ip_count":{"description":"Number of IPs purchased.","type":"integer","nullable":true}},"type":"object","nullable":true},"ip_list":{"description":"List of assigned proxy IPs. Only available for ISP and Datacenter sub-users. Included when `include=ip_list` is specified.","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"}}},"paths":{"/sub-users/{uuid}":{"get":{"tags":["Sub-Users"],"summary":"Get sub-user details","description":"Returns detailed information about a specific sub-user.","operationId":"595abae6ceab85e08a3d01a0d2daa713","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include","in":"query","description":"Comma-separated list: credentials, traffic, proxy_settings, ip_list (ISP/Datacenter only)","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SubUser"}},"type":"object"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Sub-user not found"}}}}}}
```

## Update a sub-user

> Updates sub-user settings such as password, whitelisted IPs, and priority settings.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"SubUserUpdateRequest":{"title":"Sub-User Update Request","description":"Request body for updating sub-user settings. All fields are optional - only include fields you want to change.","properties":{"password":{"description":"New proxy authentication password. Must be 6-50 characters. Only alphanumeric characters and basic symbols allowed.","type":"string","maxLength":50,"minLength":6},"whitelisted_ips":{"description":"List of whitelisted IPs. Accepts plain IP strings or objects with ip and note fields. When set, only requests from these IPs will be accepted.","type":"array","items":{"oneOf":[{"type":"string","format":"ipv4"},{"required":["ip"],"properties":{"ip":{"type":"string","format":"ipv4"},"note":{"description":"Optional label/note for this IP","type":"string"}},"type":"object"}]}},"high_priority":{"description":"Enable high priority routing for faster response times. Available for datacenter and ISP proxies. May incur additional costs.","type":"boolean"},"high_concurrency":{"description":"Enable high concurrency mode for increased simultaneous connections. Useful for high-volume scraping operations.","type":"boolean"},"proxy_bandwidth":{"description":"Bandwidth in GB, or \"unlimited\" for unlimited bandwidth. Only for datacenter and ISP sub-users.","oneOf":[{"type":"integer","maximum":1500000,"minimum":1},{"type":"string","enum":["unlimited"]}]},"proxy_ips":{"description":"Number of proxy IPs. Only for datacenter and ISP sub-users.","type":"integer","minimum":1}},"type":"object"},"SubUser":{"title":"Sub-User","description":"A sub-user represents a proxy credential that can be used for authentication. Sub-users are associated with different proxy types (datacenter, residential, ISP, IPv6) and have their own bandwidth allocations and settings.","required":["uuid","name","type","status","created_at","updated_at"],"properties":{"uuid":{"description":"Unique identifier for the sub-user. Use this UUID in all API operations.","type":"string","format":"uuid"},"name":{"description":"Username for proxy authentication. This is the login credential used when connecting to the proxy server.","type":"string"},"type":{"description":"Proxy product type. Determines the IP pool and features available.","type":"string","enum":["datacenter","residential","ipv6","isp"]},"status":{"description":"Current status of the sub-user. Only \"active\" sub-users can be used for proxy connections.","type":"string","enum":["active","expired","suspended"]},"expires_at":{"description":"Expiration date/time in ISO 8601 format. Null for sub-users with no expiration. After expiration, status changes to \"expired\".","type":"string","format":"date-time","nullable":true},"created_at":{"description":"Creation timestamp in ISO 8601 format.","type":"string","format":"date-time"},"updated_at":{"description":"Last update timestamp in ISO 8601 format.","type":"string","format":"date-time"},"credentials":{"description":"Proxy authentication credentials. Only included when `include=credentials` is specified.","properties":{"username":{"description":"Proxy authentication username.","type":"string"},"password":{"description":"Proxy authentication password.","type":"string"}},"type":"object","nullable":true},"traffic":{"description":"Bandwidth usage information. Only included when `include=traffic` is specified.","properties":{"used":{"description":"Bandwidth used in GB.","type":"number","format":"float"},"total":{"description":"Total bandwidth allocation in GB.","type":"number","format":"float"},"remaining":{"description":"Remaining bandwidth in GB.","type":"number","format":"float"},"unit":{"description":"Unit of measurement.","type":"string"}},"type":"object","nullable":true},"proxy_settings":{"description":"Advanced proxy settings. Only included when `include=proxy_settings` is specified.","properties":{"whitelisted_ips":{"description":"Allowed IP addresses.","type":"array","items":{"type":"string"}},"country_list":{"description":"Country distribution for datacenter/ISP.","type":"object"},"high_priority":{"description":"High priority routing enabled.","type":"boolean"},"high_concurrency":{"description":"High concurrency mode enabled.","type":"boolean"},"purchased_ip_count":{"description":"Number of IPs purchased.","type":"integer","nullable":true}},"type":"object","nullable":true},"ip_list":{"description":"List of assigned proxy IPs. Only available for ISP and Datacenter sub-users. Included when `include=ip_list` is specified.","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"}}},"paths":{"/sub-users/{uuid}":{"put":{"tags":["Sub-Users"],"summary":"Update a sub-user","description":"Updates sub-user settings such as password, whitelisted IPs, and priority settings.","operationId":"0573028fde977f3e61f2e0a0d75c9b49","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserUpdateRequest"}}}},"responses":{"200":{"description":"Sub-user updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/SubUser"}},"type":"object"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"404":{"description":"Sub-user not found"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Delete a sub-user

> Deletes a sub-user and associated proxy credentials. This action is irreversible.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}}},"paths":{"/sub-users/{uuid}":{"delete":{"tags":["Sub-Users"],"summary":"Delete a sub-user","description":"Deletes a sub-user and associated proxy credentials. This action is irreversible.","operationId":"bf59045086e46ac1e92347b0a9beaea4","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sub-user deleted successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"type":"object"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Sub-user not found"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Refund and delete a residential sub-user

> Calculates a pro-rated refund (80% of remaining bandwidth value) and deletes the sub-user. Use \`?preview=true\` to see the refund amount without executing. Only available for residential (IPv4/IPv6) sub-users.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}}},"paths":{"/sub-users/{uuid}/refund":{"post":{"tags":["Sub-Users"],"summary":"Refund and delete a residential sub-user","description":"Calculates a pro-rated refund (80% of remaining bandwidth value) and deletes the sub-user. Use `?preview=true` to see the refund amount without executing. Only available for residential (IPv4/IPv6) sub-users.","operationId":"c27e165f4c22219a85de75eda43cb20d","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"preview","in":"query","description":"Set to true to preview the refund amount without executing","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Refund preview or execution result","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"properties":{"refund_amount":{"type":"string"},"refund_percentage":{"type":"string"},"current_bandwidth_gb":{"type":"string"},"traffic_used_gb":{"type":"string"},"refundable_bandwidth_gb":{"type":"string"},"rate_per_gb":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Not a residential sub-user or refund limit reached"},"401":{"description":"Unauthorized"},"404":{"description":"Sub-user not found"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Get traffic information

> Returns traffic and bandwidth usage information for a sub-user.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}}},"paths":{"/sub-users/{uuid}/traffic":{"get":{"tags":["Sub-Users"],"summary":"Get traffic information","description":"Returns traffic and bandwidth usage information for a sub-user.","operationId":"9068ccd0b1bf4c73c1cf8ff2249c762f","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"properties":{"traffic_used":{"type":"integer"},"bandwidth":{"type":"integer"},"traffic_used_gb":{"type":"number","format":"float"},"bandwidth_gb":{"type":"number","format":"float"},"usage_percentage":{"type":"number","format":"float"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Sub-user not found"}}}}}}
```

## Update traffic allocation

> Updates the bandwidth allocation for a sub-user (for resellers).

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"SubUserUpdateTrafficRequest":{"title":"Sub-User Traffic Update Request","description":"Request body for updating bandwidth allocation for a sub-user. Bandwidth must match a valid pricing tier for the sub-user's IP count.","required":["bandwidth"],"properties":{"bandwidth":{"description":"Bandwidth amount in GB. Must match a valid pricing tier (e.g. 250, 1000, 5000) or \"unlimited\" (only available for 100+ IPs).","type":"string"}},"type":"object"}}},"paths":{"/sub-users/{uuid}/traffic":{"put":{"tags":["Sub-Users"],"summary":"Update traffic allocation","description":"Updates the bandwidth allocation for a sub-user (for resellers).","operationId":"70a3453e48c526018d23460e604d05c4","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserUpdateTrafficRequest"}}}},"responses":{"200":{"description":"Traffic updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"type":"object"}}}},"400":{"description":"Invalid request or insufficient bandwidth"},"401":{"description":"Unauthorized"},"403":{"description":"Not allowed for this sub-user"},"404":{"description":"Sub-user not found"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Refresh IP list

> Refreshes the IP list for datacenter/ISP sub-users. Limited to 3 refreshes per billing period.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}}},"paths":{"/sub-users/{uuid}/refresh-ips":{"post":{"tags":["Sub-Users"],"summary":"Refresh IP list","description":"Refreshes the IP list for datacenter/ISP sub-users. Limited to 3 refreshes per billing period.","operationId":"a0368563fcd5a6b97d705cbfe5e21e63","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"IP list refreshed successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"properties":{"remaining_refreshes":{"type":"integer"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Not available for this proxy type"},"401":{"description":"Unauthorized"},"403":{"description":"No refreshes remaining"},"404":{"description":"Sub-user not found"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Update country distribution

> Updates the country distribution for datacenter/ISP sub-users.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"SubUserUpdateCountriesRequest":{"title":"Sub-User Country Distribution Update Request","description":"Request body for updating the geographic distribution of IPs for datacenter and ISP sub-users. The total number of IPs across all countries must match the sub-user's purchased IP count. Limited to 3 changes per billing period.","required":["countries"],"properties":{"countries":{"description":"Country distribution map. Keys are ISO 3166-1 alpha-2 country codes (e.g., \"US\", \"GB\", \"DE\"). Values are the number of IPs to allocate to that country. The sum of all values must equal the total purchased IP count.","type":"object","additionalProperties":{"type":"integer","minimum":0}}},"type":"object"}}},"paths":{"/sub-users/{uuid}/countries":{"put":{"tags":["Sub-Users"],"summary":"Update country distribution","description":"Updates the country distribution for datacenter/ISP sub-users.","operationId":"b225cdf500ad117e4f0de2f097f69979","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserUpdateCountriesRequest"}}}},"responses":{"200":{"description":"Countries updated successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"properties":{"remaining_changes":{"type":"integer"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Invalid country distribution"},"401":{"description":"Unauthorized"},"403":{"description":"No changes remaining"},"404":{"description":"Sub-user not found"},"429":{"description":"Rate limit exceeded"}}}}}}
```

## Get bandwidth metrics

> Returns time-series bandwidth usage data for a residential (RESI\_IPv4) sub-user. Supports configurable timeframes and intervals for granular usage analysis.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Sub-Users","description":"Sub-user management endpoints"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"responses":{"Unauthorized":{"description":"Authentication failed. Ensure your API key is valid and included in the X-API-KEY header.","headers":{"WWW-Authenticate":{"description":"Authentication scheme hint","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"string","enum":["API_KEY_MISSING","INVALID_API_KEY","USER_NOT_FOUND"]},"message":{"type":"string"}},"type":"object"}},"type":"object"}}}},"NotFound":{"description":"The requested resource does not exist or you do not have access to it.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"}}}}}},"paths":{"/sub-users/{uuid}/bandwidth-metrics":{"get":{"tags":["Sub-Users"],"summary":"Get bandwidth metrics","description":"Returns time-series bandwidth usage data for a residential (RESI_IPv4) sub-user. Supports configurable timeframes and intervals for granular usage analysis.","operationId":"dc611f0653f5b485d85201de7c220272","parameters":[{"name":"uuid","in":"path","description":"Sub-user UUID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"timeframe","in":"query","description":"Predefined timeframe for the metrics window","schema":{"type":"string","default":"1day","enum":["1hour","6hours","1day","1week","1month","3months","custom"]}},{"name":"interval","in":"query","description":"Data point interval (defaults based on timeframe)","schema":{"type":"string","enum":["5min","30min","1hour","6hour","1day","1week","1month"]}},{"name":"start_date","in":"query","description":"Start date for custom timeframe (required when timeframe=custom)","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","description":"End date for custom timeframe (required when timeframe=custom)","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Bandwidth metrics retrieved successfully","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"properties":{"data":{"type":"array","items":{"properties":{"time":{"type":"string","format":"date-time"},"uploaded_bytes":{"type":"integer"},"downloaded_bytes":{"type":"integer"},"uploaded_gb":{"type":"number","format":"float"},"downloaded_gb":{"type":"number","format":"float"},"request_count":{"type":"integer"},"success_count":{"type":"integer"}},"type":"object"}},"summary":{"properties":{"total_uploaded_gb":{"type":"number","format":"float"},"total_downloaded_gb":{"type":"number","format":"float"},"total_requests":{"type":"integer"},"total_success":{"type":"integer"}},"type":"object"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Not a residential proxy or proxy username not found"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.plainproxies.com/resller-api-documentation/proxy-management/sub-users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.