> For the complete documentation index, see [llms.txt](https://docs.antivpn.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.antivpn.io/enterprise/check.md).

# Check

### Base URL

```
https://api.antivpn.io
```

***

### Endpoint

```
GET /v2/check?ip={ip_address}
```

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `ip`      | string | Yes      | The IPv4 or IPv6 address to check. |

***

### Authentication

All requests **must** include a valid API key in the `Authorization` header using the **Bearer** scheme.

```
Authorization: Bearer av_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

#### API Key Format

* Prefix: `av_live_`
* Total length: **72 characters** (`av_live_` + 64 hex characters)
* The hex portion must only contain characters `0-9`, `a-f`, or `A-F`.

If the key does not match this format, the request will be rejected immediately with a `401 Unauthorized` response.

***

### Response Format

All responses are returned as `application/json`.

#### Successful Response — `200 OK`

When the IP address is valid and the lookup succeeds, you will receive:

```json
{
  "success": true,
  "ip": "1.2.3.4",
  "proxy": true,
  "risk_score": 85,
  "processing_time": "12ms",
  "details": {
    "asn": "AS12345",
    "provider": "Example Hosting Inc.",
    "country": "US"
  }
}
```

| Field              | Type    | Description                                                                                               |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------------- |
| `success`          | boolean | Always `true` for successful lookups.                                                                     |
| `ip`               | string  | The IP address that was checked.                                                                          |
| `proxy`            | boolean | `true` if the IP is detected as a VPN, proxy, or non-residential anonymizer. `false` if it appears clean. |
| `risk_score`       | integer | A numeric score (0–100) indicating the abuse confidence level of the IP. Higher values mean higher risk.  |
| `processing_time`  | string  | Server-side latency for the lookup, formatted as milliseconds (e.g. `"5ms"`).                             |
| `details`          | object  | Additional network information about the IP.                                                              |
| `details.asn`      | string  | The Autonomous System Number in `AS{number}` format (e.g. `"AS13335"`). `"Unknown"` if unavailable.       |
| `details.provider` | string  | The name of the network provider or ISP. Falls back to the ASN type if the description is empty.          |
| `details.country`  | string  | ISO 3166-1 alpha-2 country code of the IP (e.g. `"US"`, `"DE"`). `"Unknown"` if unavailable.              |

***

#### Error Responses

All error responses share the same structure:

```json
{
  "success": false,
  "error": "error_code",
  "message": "Human-readable explanation."
}
```

| HTTP Status | `error`          | `message`                        | Cause                                                           |
| ----------- | ---------------- | -------------------------------- | --------------------------------------------------------------- |
| `401`       | `unauthorized`   | `Invalid API key.`               | Missing `Authorization` header, invalid format, or unknown key. |
| `400`       | `invalid_ip`     | `Missing or invalid IP address.` | The `ip` query parameter is missing or not a valid IP address.  |
| `500`       | `internal_error` | `Failed to check IP address.`    | An internal error occurred while looking up the IP.             |

***

### Proxy Detection Logic

An IP is flagged as `proxy: true` when **any** of the following conditions are met:

1. **Blacklisted IP** — The IP is present in the known abuser/blacklist database.
2. **Non-residential ASN type** — The ASN type is **not** one of: `isp`, `business`, `education`, `government`, or `unknown`.
3. **High risk level** — The risk level extracted from the abuse score is **not** one of: `very low`, `low`, or `elevated` (i.e., the IP has a `high` or `very high` risk level).

If none of these conditions apply, the IP is considered clean and `proxy` will be `false`.

#### Risk Score

The `risk_score` is an integer derived from the abuse confidence percentage associated with the IP's ASN data. A score of `0` means no abuse data was found.

***

### Rate Limiting & Analytics

* Every request is logged and counted toward your account's usage analytics (approved vs. blocked counts).
* The `last_used_at` timestamp on your API key is updated (debounced to once per minute).
* If your account exceeds its plan limits, requests may be restricted.

***

### Example Requests

#### cURL

```bash
curl -X GET "https://api.antivpn.io/v2/check?ip=1.2.3.4" \
  -H "Authorization: Bearer av_live_your_api_key_here"
```

#### Python

```python
import requests

headers = {
    "Authorization": "Bearer av_live_your_api_key_here"
}

response = requests.get(
    "https://api.antivpn.io/v2/check",
    params={"ip": "1.2.3.4"},
    headers=headers
)

data = response.json()

if data["success"]:
    if data["proxy"]:
        print(f"Blocked: {data['ip']} (risk: {data['risk_score']}, provider: {data['details']['provider']})")
    else:
        print(f"Allowed: {data['ip']}")
else:
    print(f"Error: {data['message']}")
```

#### JavaScript (Node.js)

```javascript
const response = await fetch("https://api.antivpn.io/v2/check?ip=1.2.3.4", {
  method: "GET",
  headers: {
    "Authorization": "Bearer av_live_your_api_key_here"
  }
});

const data = await response.json();

if (data.success) {
  console.log(`Proxy: ${data.proxy}, Risk: ${data.risk_score}`);
  console.log(`ASN: ${data.details.asn}, Provider: ${data.details.provider}, Country: ${data.details.country}`);
} else {
  console.error(`Error: ${data.message}`);
}
```

#### Java

```java
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.antivpn.io/v2/check?ip=1.2.3.4"))
    .header("Authorization", "Bearer av_live_your_api_key_here")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

***

### Best Practices

* **Cache results** — If you are checking the same IP multiple times in a short window, cache the result on your side to reduce API calls.
* **Validate IPs client-side** — Avoid sending obviously invalid IPs (e.g., empty strings, local addresses) to save quota.
* **Handle errors gracefully** — Always check the `success` field before reading other fields. Network or server errors can happen.
* **Keep your API key secret** — Never expose your `av_live_` key in client-side code, public repositories, or logs.