Proxy API

API Methods

The 2Captcha API provides convenient methods for managing proxies and retrieving information about available resources. Below is a list of available methods:

1. Account Management:
   • proxy - retrieve general account information
   • balance - check the current account balance

2. Available Locations:

   • countries - retrieve a list of available countries
   • regions - retrieve a list of available regions
   • cities - retrieve a list of available cities
   • asns - retrieve a list of ASNs

3. Whitelist Management:

   • get_white_list_ips - retrieve the list of whitelisted IP addresses
   • add_white_list_ip - add IP addresses to the whitelist
   • delete_white_list_ip - remove an IP address from the whitelist
   • create_white_list_connections - create whitelist connections
   • get_white_list_connections - retrieve the list of whitelist connections
   • white_list_connections_count - get the number of whitelist ports
   • delete_white_list_connection - delete a whitelist connection
   • delete_all_white_list_connections - delete all whitelist connections
   • white_list_errors - whitelist error codes

Retrieving General Account Information

This method allows you to obtain key details about your account, including the current status, the amount of used traffic, and the list of whitelisted IP addresses.

API Endpoint: https://api.2captcha.com/proxy?key=<API_KEY>
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy?key=1abc234de56fab7c89012d34e56fa7b8

Response example:

{
    "status": "OK",
    "data": {
        "username": "u2135p19s84m750n5",
        "status": 1,
        "total_flow": 1000,
        "use_flow": 925.679,
        "last_flow": 925.679,
        "ip_white": [
            "203.0.113.42"
        ]
    }
}

Account Balance

This method allows you to retrieve the current account balance.

API Endpoint: https://api.2captcha.com/proxy/balance?key=<API_KEY>
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/balance?key=1abc234de56fab7c89012d34e56fa7b8

Response example:

{
    "status": "OK",
    "balance": 1000
}

Available Countries

This method retrieves a list of countries where 2Captcha proxies are available.

API Endpoint: https://api.2captcha.com/proxy/locations/countries?key=<API_KEY>&page=0
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/locations/countries?key=1abc234de56fab7c89012d34e56fa7b8&page=0

Response example:

{
    "status": "OK",
    "data": [
        {
            "id": 231,
            "code": "ae",
            "title": "United Arab Emirates"
        },
        {
            "id": 232,
            "code": "gb",
            "title": "United Kingdom"
        },
        {
            "id": 233,
            "code": "us",
            "title": "United States"
        },
        ...
    ],
    "total": 208
}

Available Regions

This method retrieves a list of regions where 2Captcha proxies are available, along with their corresponding countries.

API Endpoint: https://api.2captcha.com/proxy/locations/regions?key=<API_KEY>&page=0
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/locations/regions?key=1abc234de56fab7c89012d34e56fa7b8&page=0

Response example:

{
    "status": "OK",
    "data": [
        {
            "id": 3391,
            "countryId": 231,
            "region": "dubai"
        },
        {
            "id": 2336,
            "countryId": 232,
            "region": "england"
        },
        {
            "id": 1450,
            "countryId": 233,
            "region": "colorado"
        },
        ...
    ],
    "total": 967
}

Available Cities

This method retrieves a list of cities where 2Captcha proxies are available, along with their corresponding regions and country codes.

API Endpoint: https://api.2captcha.com/proxy/locations/cities?key=<API_KEY>&page=0
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/locations/cities?key=1abc234de56fab7c89012d34e56fa7b8&page=0

Response example:

{
    "status": "OK",
    "data": [
        {
            "id": 39364,
            "city": "amiens",
            "regionId": 4828,
            "region": "hautsdefrance",
            "countryCode": "fr"
        },
        {
            "id": 63141,
            "city": "amman",
            "regionId": 965,
            "region": "amman",
            "countryCode": "jo"
        },
        {
            "id": 76411,
            "city": "ampang",
            "regionId": 1944,
            "region": "selangor",
            "countryCode": "my"
        },
        ...
    ],
    "total": 3145
}

List of ASNs

This method retrieves a list of Autonomous Systems (ASNs) through which 2Captcha proxies are provided. Each Autonomous System belongs to a specific Internet Service Provider (ISP) and has a unique ASN number.

API Endpoint: https://api.2captcha.com/proxy/locations/asns?key=<API_KEY>&page=0
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/locations/asns?key=1abc234de56fab7c89012d34e56fa7b8&page=0

Response example:

{
    "status": "OK",
    "data": [
        {
            "id": 4463,
            "title": "Sprint",
            "countryCode": "us",
            "code": "AS1239"
        },
        {
            "id": 1943,
            "title": "KCOM GROUP LIMITED",
            "countryCode": "gb",
            "code": "AS12390"
        },
        {
            "id": 2749,
            "title": "Brutele SC",
            "countryCode": "be",
            "code": "AS12392"
        },
        ...
    ],
    "total": 9830
}

Get Whitelisted IPs

This method retrieves the list of IPv4 addresses added to your whitelist. Proxies from whitelist connections can be used without authentication, but only from these IP addresses.

API Endpoint: https://api.2captcha.com/proxy/white_lists/ips?key=<API_KEY>
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/white_lists/ips?key=1abc234de56fab7c89012d34e56fa7b8

Response example:

{
    "status": "OK",
    "data": [
        "203.0.113.42",
        "198.51.100.10"
    ]
}

Add IP to Whitelist

This method adds one or more IPv4 addresses to your whitelist.

Limitations:

• only IPv4 addresses are supported;
• up to 5 IP addresses per account;
• the same IP address cannot be passed twice in one request;
• an IP address cannot be added to the whitelist of more than one account.

API Endpoint: https://api.2captcha.com/proxy/white_lists/ips?key=<API_KEY>
Method: POST
Content-Type: application/json

Query Parameters:

Request Body:

Request example:

curl -X POST "https://api.2captcha.com/proxy/white_lists/ips?key=1abc234de56fab7c89012d34e56fa7b8" \
  -H "Content-Type: application/json" \
  -d '{
    "ips": ["203.0.113.42"]
  }'

Response example:

{
    "status": "OK"
}

Remove IP from Whitelist

This method removes an IP address from your whitelist.

API Endpoint: https://api.2captcha.com/proxy/white_lists/ips?key=<API_KEY>&ip=<IP>
Method: DELETE

Request Parameters:

Request example:

curl -X DELETE "https://api.2captcha.com/proxy/white_lists/ips?key=1abc234de56fab7c89012d34e56fa7b8&ip=203.0.113.42"

Response example:

{
    "status": "OK"
}

Create Whitelist Connections

This method creates a persistent group of proxy ports (a connection) for your main proxy account. The connection can be used without authentication from the IP addresses in your whitelist. Each connection gets an id, so it can later be retrieved or deleted.

You can select a country, region, or city so that all traffic of the connection is routed through proxies in the chosen location. Use the countries, regions, and cities methods to get the available values.

API Endpoint: https://api.2captcha.com/proxy/white_lists/connections?key=<API_KEY>
Method: POST
Content-Type: application/json

Query Parameters:

Request Body:

Only count is required, so the minimal request body is {"count": 5}.
For compatibility with the deprecated method, the aliases connection_count, country, region_id, and city_id are also accepted.

Request example:

curl -X POST "https://api.2captcha.com/proxy/white_lists/connections?key=1abc234de56fab7c89012d34e56fa7b8" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 5,
    "countryCode": "de",
    "regionId": 3016,
    "cityId": 25866,
    "description": "Germany"
  }'

Response example:

{
    "status": "OK",
    "data": {
        "id": 61957,
        "portsCount": 5,
        "connections": [
            "proxy-host:10001",
            "proxy-host:10002"
        ],
        "countryCode": "de",
        "regionId": null,
        "cityId": null,
        "description": "Germany",
        "subAccount": "proxy-login",
        "masterAccount": "master-login",
        "trafficType": "traffic-type"
    }
}

The set of fields in the connection object may change. After creating a connection, get the current list of connections with the get_white_list_connections method.

List Whitelist Connections

This method retrieves the list of your whitelist connections with pagination.

API Endpoint: https://api.2captcha.com/proxy/white_lists/connections?key=<API_KEY>&page=1&limit=10
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/white_lists/connections?key=1abc234de56fab7c89012d34e56fa7b8&page=1&limit=10

Response example:

{
    "status": "OK",
    "data": {
        "data": [],
        "meta": {
            "total": 0,
            "perPage": 10,
            "currentPage": 1,
            "lastPage": 1
        }
    }
}

Whitelist Ports Count

This method returns the total number of ports in your whitelist connections. The value is returned in the data field.

API Endpoint: https://api.2captcha.com/proxy/white_lists/connections/count?key=<API_KEY>
Method: GET

Request Parameters:

Request example:

https://api.2captcha.com/proxy/white_lists/connections/count?key=1abc234de56fab7c89012d34e56fa7b8

Delete Whitelist Connection

This method deletes a whitelist connection by its id.

API Endpoint: https://api.2captcha.com/proxy/white_lists/connections/<ID>?key=<API_KEY>
Method: DELETE

Request Parameters:

Request example:

curl -X DELETE "https://api.2captcha.com/proxy/white_lists/connections/61957?key=1abc234de56fab7c89012d34e56fa7b8"

Response example:

{
    "status": "OK"
}

Delete All Whitelist Connections

This method deletes all whitelist connections of your main proxy account.

API Endpoint: https://api.2captcha.com/proxy/white_lists/connections?key=<API_KEY>
Method: DELETE

Request Parameters:

Request example:

curl -X DELETE "https://api.2captcha.com/proxy/white_lists/connections?key=1abc234de56fab7c89012d34e56fa7b8"

Response example:

{
    "status": "OK"
}

Whitelist Error Codes

In case of an error, the status field contains the error code, and the message field contains its description:

{
    "status": "ERROR_INVALID_CONNECTION_COUNT",
    "message": "Connection count is missing, invalid, or out of range (1-2000)"
}

Migrating from Deprecated Methods

The previous whitelist methods have been replaced with new ones:

The new connections method works differently from generate_white_list_connections:

• the ip parameter is no longer passed: whitelisted IP addresses are managed with the /proxy/white_lists/ips methods;
• the protocol parameter is no longer passed;
• the result is a persistent connection with an id, which can be retrieved or deleted later.

The generate_white_list_connections method no longer generates connections and returns HTTP status 410 Gone:

{
    "status": "ERROR_METHOD_DEPRECATED",
    "message": "Method is deprecated. Use POST /proxy/white_lists/connections"
}