### Example cURL Request

Source: https://docs.proxyscrape.com/api/account/authentication

Demonstrates how to make a GET request to the API keys endpoint using cURL, including the `api-token` header.

```bash
curl -X GET "https://api.proxyscrape.com/v4/account/api-keys" \
  -H "api-token: YOUR_64_CHARACTER_API_KEY"
```

--------------------------------

### Example CURL Request for Shared Datacenter Proxies

Source: https://docs.proxyscrape.com/welcome-links/premium

Demonstrates how to use CURL to make a request through a shared datacenter proxy. Includes examples for different locations.

```shell
curl -s -x 185.199.228.220:7777 -U "customer-USER:PASS" https://ipinfo.io
```

```shell
curl -s -x 91.108.4.55:7777 -U "customer-USER:PASS" https://ipinfo.io
```

```shell
curl -s -x 45.142.212.100:7777 -U "customer-USER:PASS" https://ipinfo.io
```

--------------------------------

### Permission reference

Source: https://docs.proxyscrape.com/llms.txt

A reference guide to product-specific (2-part) and account API key (3-part) permissions.

```APIDOC
## Permission Reference

### Description
Reference of product (2-part) and account API key (3-part) permissions.

### Permission Structure
- **Product Permissions**: Typically in the format `product:action` (e.g., `residential:read`, `serp_api:write`).
- **Account API Key Permissions**: Typically in the format `account:resource:action` (e.g., `account:apikeys:delete`).

### Example Permissions
- `residential:read`: Allows reading residential proxy data.
- `serp_api:write`: Allows performing write operations for the SERP API.
- `account:apikeys:delete`: Allows deleting API keys.
```

--------------------------------

### Get SERP API Overview

Source: https://docs.proxyscrape.com/api-reference/serp-api/serp-api-overview

Retrieves the SERP API subscription overview, including plan, credits used/remaining, and status. Requires `serp_api:read` permission.

```APIDOC
## GET /v4/account/{subAccountId}/serp-api/overview

### Description
Get SERP API subscription overview: plan, credits used/remaining, status. Permission: `serp_api:read`.

### Method
GET

### Endpoint
/v4/account/{subAccountId}/serp-api/overview

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The ID of the subaccount.

### Response
#### Success Response (200)
- **plan** (string) - The subscription plan.
- **credits_used** (integer) - The number of credits used.
- **credits_limit** (integer) - The total credit limit.
- **status** (string) - The subscription status.

### Request Example
```json
{
  "example": ""
}
```

### Response Example
```json
{
  "plan": "free",
  "credits_used": 10,
  "credits_limit": 100,
  "status": "active"
}
```
```

--------------------------------

### Manage IP Whitelist

Source: https://docs.proxyscrape.com/api-reference/datacenter/manage-ip-whitelist

This endpoint allows you to manage the IP whitelist for a datacenter subaccount. You can perform 'get', 'add', 'set', or 'remove' operations by specifying the 'type' query parameter. For 'add', 'set', and 'remove' operations, you must also provide the IP addresses in the 'ip[]' query parameter. The 'labels' query parameter can be used with the 'get' operation to include labels in the response.

```APIDOC
## GET /v4/account/{subAccountId}/datacenter_shared/whitelist

### Description
Manage the IP whitelist for a datacenter subaccount. All four operations share this endpoint via the required `type` query parameter.

**Operations and required permissions:**

- `get` — list current IPs (`datacenter_shared:read` or `datacenter_dedicated:read`)

- `add` — append IPs without removing existing ones (`datacenter_shared:write` or `datacenter_dedicated:write`)

- `set` — replace the entire whitelist (`datacenter_shared:write` or `datacenter_dedicated:write`)

- `remove` — delete specific IPs (`datacenter_shared:delete` or `datacenter_dedicated:delete`)

**IP label format:** For `add` and `set`, each `ip[]` value may include a label prefix separated by a colon: `ip[]=Office:1.2.3.4`. Everything before the last colon is the label; the last segment is the IP.

**Rate limit:** Mutations (`add`, `set`, `remove`) are limited to 1 request per 30 minutes per subaccount.

**Propagation:** After a successful mutation, allow up to 10 minutes for IPs to synchronize across all proxies.

### Method
GET

### Endpoint
/v4/account/{subAccountId}/datacenter_shared/whitelist

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The ID of the subaccount.

#### Query Parameters
- **type** (string) - Required - Operation to perform: `get` reads the current whitelist; `add` appends IPs to the existing list; `set` replaces the entire whitelist; `remove` deletes specific IPs.
- **ip[]** (array of strings) - Optional - One or more public IPv4 addresses to add, set, or remove. Required for `add`, `set`, and `remove`. Each value may include an optional label prefix separated by a colon — e.g. `Office:1.2.3.4` sets the label "Office" for that IP. Cannot exceed the account's `maxips` limit.
- **labels** (string) - Optional - When present (any value), the `get` response includes a `labels` object mapping each whitelisted IP to its assigned label. Has no effect for other operation types.

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation. Example: "ok"
- **maxips** (integer) - Maximum number of IPs this account is allowed to whitelist.
- **whitelisted** (array of strings) - Currently whitelisted IP addresses.
- **labels** (object) - Maps each whitelisted IP to its assigned label (only present if `labels` query parameter is used with `get` operation).

#### Response Example (type=get with labels)
{
  "status": "ok",
  "maxips": 3,
  "whitelisted": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "labels": {
    "1.2.3.4": "Office",
    "5.6.7.8": "Home"
  }
}

#### Response Example (type=get without labels)
{
  "status": "ok",
  "maxips": 3,
  "whitelisted": [
    "1.2.3.4",
    "5.6.7.8"
  ]
}

#### Response Example (type=add, set, or remove)
{
  "status": "ok"
}
```

--------------------------------

### Get Permission Context

Source: https://docs.proxyscrape.com/llms.txt

Returns the permission structure and allowed permissions for your account.

```APIDOC
## Get Permission Context

### Description
Retrieves the hierarchical structure of permissions and the specific permissions allowed for your account. This information is valuable for building user interfaces for permission selection or for validating permissions before creating or updating API keys.

### Permission
`account:apikeys:read`

### Method
GET

### Endpoint
`/account/permissions/context`

### Response
#### Success Response (200)
- **structure** (object) - An object representing the permission hierarchy.
- **allowed_permissions** (array) - A list of all permissions that can be granted.

#### Response Example
```json
{
  "structure": {
    "account": {
      "apikeys": [
        "read",
        "write"
      ]
    }
  },
  "allowed_permissions": [
    "account:apikeys:read",
    "account:apikeys:write"
  ]
}
```
```

--------------------------------

### Get Residential Overview

Source: https://docs.proxyscrape.com/api-reference/residential/residential-overview

Retrieves an overview of the residential subscription, including plan, bandwidth used and remaining, and status. Requires the `residential:read` permission.

```APIDOC
## GET /v4/account/{subAccountId}/residential/overview

### Description
Get residential subscription overview: plan, bandwidth used/remaining, status. Permission: `residential:read`.

### Method
GET

### Endpoint
/v4/account/{subAccountId}/residential/overview

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The ID of the subaccount.

### Response
#### Success Response (200)
- **plan** (string) - The subscription plan.
- **bandwidth_used** (integer) - The amount of bandwidth used.
- **bandwidth_limit** (integer) - The total bandwidth limit.
- **status** (string) - The status of the subscription.

### Request Example
```json
{
  "example": ""
}
```

### Response Example
```json
{
  "plan": "string",
  "bandwidth_used": 0,
  "bandwidth_limit": 0,
  "status": "string"
}
```
```

--------------------------------

### Get Datacenter Proxy List

Source: https://docs.proxyscrape.com/api-reference/datacenter/get-datacenter-proxy-list

Fetches a list of datacenter proxies. Authentication is required using an API token.

```APIDOC
## GET /api/v4/datacenter/list

### Description
Retrieves a list of datacenter proxies.

### Method
GET

### Endpoint
/api/v4/datacenter/list

### Parameters
#### Query Parameters
- **format** (string) - Optional - The output format for the proxy list. Supported values: `json`, `text`, `csv`, `credentials`.
- **country** (string) - Optional - Filters proxies by country code (e.g., `US`, `DE`).
- **state** (string) - Optional - Filters proxies by state or region.
- **city** (string) - Optional - Filters proxies by city.

### Response
#### Success Response (200)
- **proxies** (array) - A list of proxy objects, each containing `ip` and `port`.

#### Response Example
```json
{
  "proxies": [
    {
      "ip": "1.2.3.4",
      "port": 10001
    },
    {
      "ip": "5.6.7.8",
      "port": 10002
    }
  ]
}
```

#### Error Responses
- **401 Unauthorized**
  - Description: The subaccount's subscription has expired.
  - Content:
    - `application/json`:
      ```json
      {
        "status": "unauthorized",
        "info": "Your subscription is expired."
      }
      ```
- **403 Forbidden**
  - Description: Credential-based authentication is not enabled for this account. Returned only when `format=credentials`.
  - Content:
    - `application/json`:
      ```json
      {
        "error": "Credential-based authentication is not enabled for this account."
      }
      ```
- **404 Not Found**
  - Description: Subaccount not found.
  - Content:
    - `text/plain`:
      ```
      Subaccount not found.
      ```

### Security
- **apiToken**: API key. Create and manage keys at `/v4/account/api-keys` or in the dashboard.
```

--------------------------------

### Get Proxy List

Source: https://docs.proxyscrape.com/llms.txt

Returns a list of free proxies. Use query parameters to filter by protocol, country, timeout, and anonymity.

```APIDOC
## Get Proxy List

### Description
Fetches a list of free proxies. You can filter the results by protocol (HTTP, HTTPS, SOCKS4, SOCKS5), country, timeout, and anonymity level.

### Method
GET

### Endpoint
`/public-api/get-proxy-list`

### Parameters
#### Query Parameters
- **protocol** (string) - Optional - Filter by proxy protocol (e.g., `http`, `https`, `socks4`, `socks5`).
- **country** (string) - Optional - Filter by country code (e.g., `US`, `GB`).
- **timeout** (integer) - Optional - Filter by maximum timeout in milliseconds.
- **anonymity** (string) - Optional - Filter by anonymity level (e.g., `anonymous`, `elite`, `transparent`).
- **format** (string) - Optional - The desired output format (e.g., `json`, `txt`). Defaults to `json`.

### Response
#### Success Response (200)
- **proxies** (array) - A list of proxy objects, each containing:
  - **ip** (string) - The IP address of the proxy.
  - **port** (integer) - The port number of the proxy.
  - **protocol** (string) - The protocol of the proxy.
  - **country** (string) - The country of the proxy.
  - **timeout** (integer) - The timeout for the proxy.
  - **anonymity** (string) - The anonymity level of the proxy.

#### Response Example
```json
{
  "proxies": [
    {
      "ip": "1.2.3.4",
      "port": 8080,
      "protocol": "http",
      "country": "US",
      "timeout": 500,
      "anonymity": "anonymous"
    }
  ]
}
```
```

--------------------------------

### Get Residential Login Info

Source: https://docs.proxyscrape.com/llms.txt

Get login credentials for the residential subaccount.

```APIDOC
## Get Residential Login Info

### Description
Retrieves the login credentials (username and password) required to access the residential proxy service.

### Permission
`residential:read`

### Method
GET

### Endpoint
`/residential/login-info`

### Response
#### Success Response (200)
- **username** (string) - The username for the residential proxy subaccount.
- **password** (string) - The password for the residential proxy subaccount.

#### Response Example
```json
{
  "username": "residential_user",
  "password": "residential_pass123"
}
```
```

--------------------------------

### Get Subuser Statistics for Residential Proxies

Source: https://docs.proxyscrape.com/llms.txt

Get usage statistics for a residential subuser.

```APIDOC
## Get Subuser Statistics for Residential Proxies

### Description
Fetches detailed usage statistics for a specific residential subuser, allowing for granular monitoring of proxy consumption.

### Permission
`residential:read`

### Method
GET

### Endpoint
`/residential/subuser-statistic/{subuser_id}`

### Parameters
#### Path Parameters
- **subuser_id** (string) - Required - The unique identifier of the subuser for whom to retrieve statistics.

### Response
#### Success Response (200)
- **subuser_id** (string) - The ID of the subuser.
- **bandwidth_used** (integer) - Bandwidth consumed by the subuser in MB.
- **requests_count** (integer) - The total number of requests made by the subuser.

#### Response Example
```json
{
  "subuser_id": "sub_abc123",
  "bandwidth_used": 500,
  "requests_count": 1000
}
```
```

--------------------------------

### Get Residential Unlimited Statistics

Source: https://docs.proxyscrape.com/llms.txt

Get usage statistics for the residential unlimited subaccount.

```APIDOC
## Get Residential Unlimited Statistics

### Description
Retrieves usage statistics for your residential unlimited subaccount, allowing you to monitor your proxy consumption.

### Permission
`residential_unlimited:read`

### Method
GET

### Endpoint
`/residential-unlimited/statistics`

### Response
#### Success Response (200)
- **used_bandwidth** (integer) - Bandwidth consumed in MB.
- **remaining_bandwidth** (integer) - Bandwidth remaining in MB.
- **total_bandwidth** (integer) - Total bandwidth allocated in MB.
- **active_sessions** (integer) - Number of currently active proxy sessions.

#### Response Example
```json
{
  "used_bandwidth": 5000,
  "remaining_bandwidth": 15000,
  "total_bandwidth": 20000,
  "active_sessions": 150
}
```
```

--------------------------------

### Create a key

Source: https://docs.proxyscrape.com/llms.txt

Information on how to create your first API key via the dashboard or additional keys via the dashboard or API.

```APIDOC
## Create API Key

### Description
Create your first API key from the dashboard; create additional keys via the dashboard or the API.

### Method
POST (via API)

### Endpoint
/account/create-key (example, actual endpoint may vary)

### Parameters
#### Query Parameters
- **api_token** (string) - Required - Your API key for authentication (if creating via API).

#### Request Body (if creating via API)
- **name** (string) - Required - The name for the new API key.
- **permissions** (array) - Optional - Permissions to assign to the new key.

### Response
#### Success Response (200)
- **key_id** (string) - The ID of the newly created API key.
- **api_key** (string) - The newly generated API key.

#### Response Example (if creating via API)
{
  "key_id": "key_abc123",
  "api_key": "YOUR_NEW_API_KEY"
}
```

--------------------------------

### Get Usage Requests

Source: https://docs.proxyscrape.com/llms.txt

Get recent API usage requests for the datacenter subaccount.

```APIDOC
## Get Usage Requests

### Description
Retrieves recent API usage requests for the datacenter subaccount.

### Permission
`datacenter_shared:read` or `datacenter_dedicated:read`

### Method
GET

### Endpoint
`/datacenter/usage-requests`

### Response
#### Success Response (200)
- **requests** (array) - A list of recent API usage requests, each containing details like timestamp, IP, and status.

#### Response Example
```json
{
  "requests": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "ip": "1.2.3.4",
      "status": "success"
    }
  ]
}
```
```

--------------------------------

### Try the API

Source: https://docs.proxyscrape.com/api-overview

You can test the API endpoints directly from the documentation using the 'Try now' feature available on each endpoint page. For Account API endpoints, you will be prompted to enter your API key, which will be sent in the `api-token` header.

```APIDOC
## Try the API

Use **Try now** on each endpoint page to send requests directly from the docs. For Account API endpoints, enter your API key when prompted so the playground sends it in the `api-token` header.
```

--------------------------------

### Get Subuser Response Time Status

Source: https://docs.proxyscrape.com/llms.txt

Get response time status for residential subusers.

```APIDOC
## Get Subuser Response Time Status

### Description
Retrieves the response time status for each of your residential subusers, helping you monitor performance and identify potential issues.

### Permission
`residential:read`

### Method
GET

### Endpoint
`/residential/subuser-response-time-status`

### Response
#### Success Response (200)
- **subusers_status** (object) - An object where keys are subuser IDs and values are their response time status (e.g., `fast`, `average`, `slow`).

#### Response Example
```json
{
  "subusers_status": {
    "sub_abc123": "fast",
    "sub_def456": "average"
  }
}
```
```

--------------------------------

### Account API Overview

Source: https://docs.proxyscrape.com/api-overview

The Account API is recommended for all authenticated access. You can create and manage API keys from the dashboard or programmatically via the API. Send your API token in the `api-token` header when calling `/v4/account/...` endpoints. Browse the Account API section for guides on creating keys, authentication, permissions, and more.

```APIDOC
## Account API

**Recommended for all authenticated access.** Create and manage API keys from the [dashboard](https://dashboard.proxyscrape.com/v2/account/api-keys) or programmatically via the API. Send your API token in the `api-token` header when calling `/v4/account/...` endpoints.

Browse the **Account API** section in the sidebar for guides on creating keys, authentication, permissions, and more. Each endpoint page (API key management, Subaccounts, Datacenter, Residential, Residential unlimited, SERP API) has **Try now**.
```

--------------------------------

### Get API Key

Source: https://docs.proxyscrape.com/llms.txt

Get a single API key by its UUID. Returns metadata only — the secret is never returned after creation.

```APIDOC
## Get API Key

### Description
Retrieves metadata for a specific API key using its UUID. The secret key is never returned after its initial creation.

### Permission
`account:apikeys:read`

### Method
GET

### Endpoint
`/account/apikeys/{uuid}`

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier (UUID) of the API key.

### Response
#### Success Response (200)
- **id** (string) - The UUID of the API key.
- **name** (string) - The name of the API key.
- **permissions** (array) - A list of permissions granted to the API key.
- **scopes** (array) - A list of scopes associated with the API key.
- **expiry** (string) - The expiration date of the API key in ISO 8601 format.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "My Test Key",
  "permissions": ["datacenter:read"],
  "scopes": ["global"],
  "expiry": "2024-12-31T23:59:59Z"
}
```
```

--------------------------------

### Get Datacenter Overview

Source: https://docs.proxyscrape.com/api-reference/datacenter/datacenter-overview

Fetches the datacenter subscription overview for a specified subaccount. This includes plan details, the number of proxies available, the subscription status, and the expiration date. Requires `datacenter_shared:read` or `datacenter_dedicated:read` permission.

```APIDOC
## GET /v4/account/{subAccountId}/datacenter_shared/overview

### Description
Get datacenter subscription overview for a subaccount: plan details, proxy count, status, and expiration. Permission: `datacenter_shared:read` or `datacenter_dedicated:read`.

### Method
GET

### Endpoint
/v4/account/{subAccountId}/datacenter_shared/overview

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The unique identifier for the subaccount.

#### Request Body
None

### Response
#### Success Response (200)
- **plan** (string) - The name of the subscription plan.
- **proxy_count** (integer) - The total number of proxies available.
- **status** (string) - The current status of the subscription (e.g., active, expired).
- **expires_at** (string) - The date and time when the subscription expires.

#### Response Example
```json
{
  "plan": "premium",
  "proxy_count": 1000,
  "status": "active",
  "expires_at": "2024-12-31T23:59:59Z"
}
```
```

--------------------------------

### Retrieve Full Permission Context

Source: https://docs.proxyscrape.com/api/account/permission-reference

To get the complete, up-to-date list and structure of all permissions, including any account-specific ones, call the `GET /v4/account/api-keys/permission-context` endpoint.

```APIDOC
## Retrieve Full Permission Context

For the complete, up-to-date list and structure (including any account-specific permissions), call **GET /v4/account/api-keys/permission-context**.
```

--------------------------------

### Product Permissions

Source: https://docs.proxyscrape.com/api/account/permission-reference

Product permissions follow the format `resource:action`. Typical actions include 'read', 'write', and 'delete'. This section details specific product permissions like `datacenter_shared`, `datacenter_dedicated`, `residential`, `residential_unlimited`, `serp_api`, and `subaccount`.

```APIDOC
## Product Permissions (2-part: resource:action)

Permissions follow the form `resource:action`. Typical actions:

* **read** — Read proxy lists, account/product info, and list resources.
* **write** — Create or update resources (e.g. whitelist, settings).
* **delete** — Revoke access, remove resources, or delete data.

| Permission                     | Description                                                                                     |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| `datacenter_shared:read`       | Read shared datacenter proxy list and account info.                                             |
| `datacenter_shared:write`      | Manage shared datacenter settings (e.g. whitelist).                                             |
| `datacenter_shared:delete`     | Revoke or remove shared datacenter access.                                                      |
| `datacenter_dedicated:read`    | Read dedicated datacenter proxy list and account info.                                          |
| `datacenter_dedicated:write`   | Manage dedicated datacenter settings (e.g. whitelist).                                          |
| `datacenter_dedicated:delete`  | Revoke or remove dedicated datacenter access.                                                   |
| `residential:read`             | Read residential proxy list and account info.                                                   |
| `residential:write`            | Create, update, and reset password for residential subusers.                                    |
| `residential:delete`           | Revoke or remove residential access.                                                            |
| `residential_unlimited:read`   | Read residential_unlimited proxy list and account info.                                        |
| `residential_unlimited:write`  | Manage residential_unlimited settings (e.g. whitelist).                                        |
| `residential_unlimited:delete` | Revoke or remove residential_unlimited access. Not used by any Account API endpoint currently. |
| `serp_api:read`                | Read SERP API usage and account info.                                                           |
| `serp_api:write`               | Manage SERP API settings.                                                                       |
| `serp_api:delete`              | Revoke or remove SERP API access.                                                               |

### Subaccount permissions

| Permission         | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `subaccount:read`  | List subaccounts, get preferences, countries available. |
| `subaccount:write` | Update subaccount preferences.                          |
```

--------------------------------

### Include API Token Header

Source: https://docs.proxyscrape.com/api/account/authentication

Send your API key in the `api-token` header for all requests to the Account API.

```bash
api-token: <your-key>
```

--------------------------------

### OpenAPI Specification for Get Subusers

Source: https://docs.proxyscrape.com/api-reference/residential/get-subusers

This OpenAPI 3.0.3 specification defines the GET endpoint for retrieving residential subusers. It outlines the request parameters, response structure, and authentication method.

```yaml
openapi: 3.0.3
info:
  title: ProxyScrape Account API
  description: Account API — authenticate with the api-token header.
  version: 1.0.0
servers:
  - url: https://api.proxyscrape.com
    description: ProxyScrape API
security:
  - apiToken: []
tags:
  - name: API key management
    description: Create, list, update, regenerate, and revoke API keys
  - name: Subaccounts
    description: List subaccounts and manage preferences
  - name: Datacenter
    description: 'Datacenter shared and dedicated: overview, proxy list, usage, whitelist'
  - name: Residential
    description: 'Residential (bandwidth): overview, subusers, usage'
  - name: Residential unlimited
    description: 'Residential unlimited: overview, statistics, password'
  - name: SERP API
    description: 'SERP API: overview, subusers, search'
paths:
  /v4/account/{subAccountId}/residential/subuser/get:
    get:
      tags:
        - Residential
      summary: Get subuser(s)
      description: >-
        List all residential subusers for a subaccount. Permission:
        `residential:read`.
      operationId: getResidentialSubusers
      parameters:
        - name: subAccountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of subusers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    username:
                      type: string
                    created_at:
                      type: string
      security:
        - apiToken: []
components:
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: api-token
      description: >-
        API key. Create and manage keys at /v4/account/api-keys or in the
        dashboard.

```

--------------------------------

### List Residential Unlimited Countries (OpenAPI)

Source: https://docs.proxyscrape.com/api-reference/residential-unlimited/countries

Use this OpenAPI specification to understand the structure and parameters for fetching available countries for residential unlimited proxies. Requires the `residential_unlimited:read` permission.

```yaml
openapi: 3.0.3
info:
  title: ProxyScrape Account API
  description: Account API — authenticate with the api-token header.
  version: 1.0.0
servers:
  - url: https://api.proxyscrape.com
    description: ProxyScrape API
security:
  - apiToken: []
tags:
  - name: API key management
    description: Create, list, update, regenerate, and revoke API keys
  - name: Subaccounts
    description: List subaccounts and manage preferences
  - name: Datacenter
    description: 'Datacenter shared and dedicated: overview, proxy list, usage, whitelist'
  - name: Residential
    description: 'Residential (bandwidth): overview, subusers, usage'
  - name: Residential unlimited
    description: 'Residential unlimited: overview, statistics, password'
  - name: SERP API
    description: 'SERP API: overview, subusers, search'
paths:
  /v4/account/{subAccountId}/residential-unlimited/countries:
    get:
      tags:
        - Residential unlimited
      summary: Countries
      description: >-
        List available countries for residential unlimited proxies. Permission:
        `residential_unlimited:read`.
      operationId: getResidentialUnlimitedCountries
      parameters:
        - name: subAccountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Available countries
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                    name:
                      type: string
      security:
        - apiToken: []
components:
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: api-token
      description: >-
        API key. Create and manage keys at /v4/account/api-keys or in the
        dashboard.

```

--------------------------------

### Get Residential Subusers

Source: https://docs.proxyscrape.com/llms.txt

List all residential subusers for a subaccount.

```APIDOC
## Get Residential Subusers

### Description
Retrieves a list of all subusers configured for your residential proxy subaccount.

### Permission
`residential:read`

### Method
GET

### Endpoint
`/residential/subusers`

### Response
#### Success Response (200)
- **subusers** (array) - A list of subuser objects, each containing:
  - **id** (string) - The unique identifier of the subuser.
  - **username** (string) - The username of the subuser.
  - **created_at** (string) - The timestamp when the subuser was created.

#### Response Example
```json
{
  "subusers": [
    {
      "id": "sub_abc123",
      "username": "subuser_test",
      "created_at": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### OpenAPI Specification for Get API Key

Source: https://docs.proxyscrape.com/api-reference/get-api-key

This OpenAPI 3.0.3 specification defines the GET /v4/account/api-keys/{id} endpoint. It outlines the request parameters, response structures for success (200 OK) and various error conditions (401, 404, 500), and security requirements using an API token.

```yaml
openapi: 3.0.3
info:
  title: ProxyScrape Account API
  description: Account API — authenticate with the api-token header.
  version: 1.0.0
servers:
  - url: https://api.proxyscrape.com
    description: ProxyScrape API
security:
  - apiToken: []
tags:
  - name: API key management
    description: Create, list, update, regenerate, and revoke API keys
  - name: Subaccounts
    description: List subaccounts and manage preferences
  - name: Datacenter
    description: 'Datacenter shared and dedicated: overview, proxy list, usage, whitelist'
  - name: Residential
    description: 'Residential (bandwidth): overview, subusers, usage'
  - name: Residential unlimited
    description: 'Residential unlimited: overview, statistics, password'
  - name: SERP API
    description: 'SERP API: overview, subusers, search'
paths:
  /v4/account/api-keys/{id}:
    get:
      tags: []
      summary: Get API key
      description: >-
        Get a single API key by its UUID. Returns metadata only — the secret is
        never returned after creation. Permission: `account:apikeys:read`.
      operationId: getApiKey
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: API key metadata (no secret)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      permissions:
                        type: array
                        items:
                          type: string
                      allowed_subaccounts:
                        type: array
                        items:
                          type: string
                      allowed_ips:
                        type: array
                        items:
                          type: string
                      expires_at:
                        type: integer
                        nullable: true
                      is_active:
                        type: boolean
                      last_used_at:
                        type: integer
                        nullable: true
                        description: Unix timestamp of last use. Null if never used.
                      token_preview:
                        type: string
                        nullable: true
                      created_at:
                        type: integer
                        description: Unix timestamp of creation.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: API key not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: API key not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Failed to fetch API key
      security:
        - apiToken: []
components:
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: api-token
      description: >-
        API key. Create and manage keys at /v4/account/api-keys or in the
        dashboard.

```

--------------------------------

### Account API overview

Source: https://docs.proxyscrape.com/llms.txt

Provides an overview of what API keys are and how they function across different ProxyScrape products.

```APIDOC
## Account API Overview

### Description
What API keys are and how they work across ProxyScrape products.

### Key Concepts
- **API Keys**: Credentials used to authenticate requests to the ProxyScrape API.
- **Permissions**: Define the level of access an API key has to different products and features.
- **Scopes and Restrictions**: Allow limiting API key access through subaccount scoping, IP restrictions, and expiration dates.
```

--------------------------------

### Get Residential Unlimited Overview

Source: https://docs.proxyscrape.com/api-reference/residential-unlimited/residential-unlimited-overview

Fetches the overview of the Residential Unlimited subscription. This includes details about the current plan, subscription status, and connection parameters. Requires `residential_unlimited:read` permission.

```APIDOC
## GET /v4/account/{subAccountId}/residential-unlimited/overview

### Description
Get residential unlimited subscription overview: plan, status, connection details. Permission: `residential_unlimited:read`.

### Method
GET

### Endpoint
/v4/account/{subAccountId}/residential-unlimited/overview

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The ID of the sub-account for which to retrieve the overview.

### Response
#### Success Response (200)
- **plan** (string) - The name of the current subscription plan.
- **status** (string) - The current status of the subscription (e.g., active, inactive).
- **speed** (string) - Information about the connection speed.

### Request Example
```json
{
  "example": ""
}
```

### Response Example
```json
{
  "plan": "premium",
  "status": "active",
  "speed": "100Mbps"
}
```
```

--------------------------------

### Get Allowed Permissions

Source: https://docs.proxyscrape.com/llms.txt

Returns the flat list of permissions you may grant to API keys.

```APIDOC
## Get Allowed Permissions

### Description
Returns a flat list of all available permissions that can be granted to API keys. This is useful for populating permission selection UIs or validating permission arrays during API key creation.

### Permission
`account:apikeys:read`

### Method
GET

### Endpoint
`/account/apikeys/permissions`

### Response
#### Success Response (200)
- **permissions** (array) - A list of strings, where each string is a valid permission.

#### Response Example
```json
{
  "permissions": [
    "datacenter_shared:read",
    "residential:write"
  ]
}
```
```

--------------------------------

### Permissions

Source: https://docs.proxyscrape.com/llms.txt

Explains how API key permissions function, how to select them in the dashboard, and how to discover them via the API.

```APIDOC
## Permissions

### Description
How API key permissions work, how to choose them in the dashboard, and how to discover them via the API.

### Key Concepts
- **Granular Control**: Permissions allow you to grant specific access levels to API keys.
- **Dashboard Selection**: Permissions can be selected when creating or editing API keys in the ProxyScrape dashboard.
- **API Discovery**: You can often retrieve available permissions or the permissions of an existing key via specific API endpoints (refer to relevant API documentation).
```

--------------------------------

### Get Subuser(s)

Source: https://docs.proxyscrape.com/api-reference/residential/get-subusers

Lists all residential subusers for a specified subaccount. This operation requires the `residential:read` permission.

```APIDOC
## GET /v4/account/{subAccountId}/residential/subuser/get

### Description
List all residential subusers for a subaccount. Permission: `residential:read`.

### Method
GET

### Endpoint
/v4/account/{subAccountId}/residential/subuser/get

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The unique identifier of the subaccount.

#### Request Body
This endpoint does not accept a request body.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the subuser.
- **username** (string) - The username of the subuser.
- **created_at** (string) - The timestamp when the subuser was created.

#### Response Example
```json
[
  {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "username": "subuser1",
    "created_at": "2023-10-27T10:00:00Z"
  }
]
```
```

--------------------------------

### Discover Available Permissions Structure

Source: https://docs.proxyscrape.com/api/account/permissions

Retrieve the complete structure of available permissions, including resources, actions, and account API key permissions, and how they apply to your account.

```APIDOC
## GET /v4/account/api-keys/permission-context

### Description
Returns the full structure of available permissions (resources, actions, and account API key permissions) and how they apply to your account.

### Method
GET

### Endpoint
/v4/account/api-keys/permission-context

### Response
#### Success Response (200)
- **structure** (object) - The hierarchical structure of permissions.
- **allowed_permissions** (array) - A flat list of permission strings you are allowed to grant.
```

--------------------------------

### Get Subaccount Preferences

Source: https://docs.proxyscrape.com/api-reference/subaccounts/get-subaccount-preferences

Fetches the preferences (label, visibility) for a given subaccount. Requires `subaccount:read` permission.

```APIDOC
## GET /v4/account/subaccounts/{subAccountId}/preferences

### Description
Get preferences for a subaccount (label, visibility). Permission: `subaccount:read`.

### Method
GET

### Endpoint
/v4/account/subaccounts/{subAccountId}/preferences

### Parameters
#### Path Parameters
- **subAccountId** (string) - Required - The unique identifier for the subaccount (UUID format).

### Responses
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the subaccount preferences.
  - **AccountID** (string) - The unique identifier of the account (UUID format).
  - **AccountType** (string) - The type of the account.
  - **label** (string) - The label assigned to the subaccount.
  - **is_hidden** (boolean) - Indicates if the subaccount is hidden.
  - **time_added** (integer) - Unix timestamp indicating when the subaccount was added.

#### Error Response (401)
- Unauthorized

#### Error Response (404)
- Subaccount not found
```

--------------------------------

### Create API Key

Source: https://docs.proxyscrape.com/api-reference/create-api-key

This endpoint allows you to create a new API key for your account. Ensure you have the necessary permissions.

```APIDOC
## POST /v4/account/api-keys

### Description
Creates a new API key for the authenticated account.

### Method
POST

### Endpoint
/v4/account/api-keys

### Parameters
#### Request Body
- **permissions** (array[string]) - Required - A list of permissions to associate with the API key.
- **subaccounts** (array[string]) - Optional - A list of subaccount IDs to associate with the API key.
- **ips** (array[string]) - Optional - A list of IP addresses or CIDR ranges allowed to use the API key.

### Request Example
```json
{
  "permissions": ["read", "write"],
  "subaccounts": ["subaccount123"],
  "ips": ["192.168.1.1/24"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **api_key** (string) - The newly created API key.
- **permissions** (array[string]) - The permissions associated with the API key.
- **subaccounts** (array[string]) - The subaccounts associated with the API key.
- **ips** (array[string]) - The allowed IPs for the API key.

#### Response Example
```json
{
  "success": true,
  "api_key": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permissions": ["read", "write"],
  "subaccounts": ["subaccount123"],
  "ips": ["192.168.1.1/24"]
}
```

#### Error Responses
- **400 Bad Request**: Invalid request payload.
- **401 Unauthorized**: Authentication failed. Ensure your API token is valid.
- **403 Forbidden**: Permission not allowed for your account, or permission escalation attempt.
  - **error** (string) - Description of the error.
  - **invalid_permissions** (array[string]) - Present when the error is a permission scope violation.
  - **excess_permissions** (array[string]) - Present when the error is a permission escalation attempt.
- **422 Unprocessable Entity**: Validation error — invalid permissions, invalid subaccounts, invalid IPs, or no valid permissions provided.
  - **error** (string) - Description of the error.
  - **messages** (object) - Field-level validation errors.
  - **invalid_permissions** (array[string]) - Present when unknown permission strings are provided.
  - **invalid_subaccounts** (array[string]) - Present when subaccount IDs don't belong to your account.
  - **invalid_ips** (array[string]) - Present when IP addresses or CIDR ranges are malformed.
- **500 Internal Server Error**: Internal server error.
  - **success** (boolean) - Always false.
  - **error** (string) - Example: "Failed to create API key"

### Security
- **apiToken**: Requires an API key passed in the `api-token` header.
```