> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /ip-classify

> Classify any IP address as residential, hosting, mobile, VPN, Tor, or proxy, with a confidence score and per-signal breakdown.

## Endpoint

```
GET https://api.bunny.build/api/v1/ip-classify?ip={ip}
```

## Authentication

| Header      | Required | Value                    |
| ----------- | -------- | ------------------------ |
| `X-API-Key` | Yes      | Your API key (`bun_...`) |

## Overview

Classify any IP address as residential, hosting/datacenter, mobile, VPN, Tor exit node, or open proxy. Bunny's IP Classification API returns a classification label, confidence score, and a full signal breakdown, so you can make precise decisions about traffic sources.

## Use cases

* Detect and block VPN, proxy, and Tor traffic
* Identify bot and datacenter traffic
* Enforce geo-based access controls
* Fraud prevention and risk scoring

## Details

Supports both IPv4 and IPv6. The `confidence` field (0–1) indicates classification certainty. The `signals` object breaks down each signal individually so you can apply your own logic.

## Query parameters

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `ip`      | string | Yes      | Valid IPv4 or IPv6 address |

## Response

### 200 OK

| Field            | Type   | Description                                                                  |
| ---------------- | ------ | ---------------------------------------------------------------------------- |
| `ip`             | string | The IP that was checked                                                      |
| `classification` | string | One of: `hosting`, `residential`, `mobile`, `vpn`, `tor`, `proxy`, `unknown` |
| `confidence`     | number | 0.0 to 1.0                                                                   |
| `signals`        | object | Boolean flags (see below)                                                    |
| `network`        | object | ASN, org, provider (see below)                                               |
| `geo`            | object | country (see below)                                                          |

**signals**

| Field            | Type    |
| ---------------- | ------- |
| `is_hosting`     | boolean |
| `is_residential` | boolean |
| `is_mobile`      | boolean |
| `is_vpn`         | boolean |
| `is_tor`         | boolean |
| `is_proxy`       | boolean |

**network**

| Field      | Type           | Description                |
| ---------- | -------------- | -------------------------- |
| `asn`      | int \| null    | Autonomous System Number   |
| `org`      | string \| null | Organization name          |
| `provider` | string \| null | Friendly name (e.g. "AWS") |

**geo**

| Field     | Type           | Description                                   |
| --------- | -------------- | --------------------------------------------- |
| `country` | string \| null | ISO 3166-1 alpha-2 country code (e.g. `"US"`) |

**Example**

```json theme={null}
{
  "ip": "8.8.8.8",
  "classification": "hosting",
  "confidence": 0.9,
  "signals": {
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false
  },
  "network": {
    "asn": 15169,
    "org": "Google LLC",
    "provider": "Google Cloud"
  },
  "geo": {
    "country": "US"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

Invalid IP format.

```json theme={null}
{
  "detail": "Invalid IP address format"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl "https://api.bunny.build/api/v1/ip-classify?ip=8.8.8.8" \
  -H "X-API-Key: bun_your_api_key"
```