# Read an autonomous system and its prefixes

`GET /api/v1/ip/asn/{asn}`

- Authentication: Secret API key as a bearer token
- Billing: 1 credit per answered system, free for the next seven days for the same number. An unknown number (404) and a server without the index (501) cost nothing.
- Group: IP

The reverse of an address lookup's `asn` field: one autonomous system with the organisation operating it, the registry that allocated the number with the country and date it recorded, what the operator lists say about it (Spamhaus ASN-DROP, the curated satellite and mobile-carrier lists, tri-state like the address flags), and every prefix the DB-IP ASN database assigns to it — `prefix_count` per family is always whole, `prefixes` carries at most 500 per family and `truncated` says when it was cut. It is read from an index the server rebuilds from the ASN database once a month after it syncs; `sources` dates both.

A number the database assigns no prefix to — a reserved or private number, a system that has never held address space, a typo — answers `404 ASN_NOT_FOUND` and costs nothing; a server that has not built the index yet answers `501 ASN_INDEX_UNAVAILABLE`, also free. It is a fact about the database, not the registry: the RIR statistics may well have allocated the number.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `asn` | path | integer | yes | The autonomous system number, without the AS prefix. |

## Example request

```bash
curl https://spaw.co/api/v1/ip/asn/15169 \
  -H "Authorization: Bearer sk_live_…"
```

## Responses

### 200 — The system, its facts and its prefixes.

```json
{
    "success": true,
    "data": {
        "asn": 15169,
        "org": "Google LLC",
        "asn_type": "hosting",
        "registry": "arin",
        "registry_country": "US",
        "allocated_at": "2000-03-30",
        "is_blocklisted": false,
        "blocklist": null,
        "is_satellite": false,
        "is_mobile": false,
        "prefix_count": {
            "ipv4": 157,
            "ipv6": 28
        },
        "prefixes": {
            "ipv4": [
                "8.8.4.0/24",
                "8.8.8.0/24",
                "8.34.208.0/20",
                "8.35.192.0/20",
                "34.4.0.0/14"
            ],
            "ipv6": [
                "2001:4860::/32",
                "2404:6800::/32",
                "2607:f8b0::/32",
                "2800:3f0::/32",
                "2a00:1450::/32"
            ]
        },
        "truncated": false,
        "sources": [
            {
                "dataset": "asn-prefixes",
                "version": "2026-09-12"
            },
            {
                "dataset": "dbip-asn-lite",
                "version": "2026-09"
            },
            {
                "dataset": "rir-allocations",
                "version": "2026-09-12"
            },
            {
                "dataset": "threat-blocklists",
                "version": "2026-09-12"
            },
            {
                "dataset": "satellite-asns",
                "version": "2026-09-12"
            },
            {
                "dataset": "mobile-carrier-asns",
                "version": "2026-09-12"
            }
        ]
    },
    "meta": {
        "credits_used": 1,
        "credits_remaining": 8,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 401 — The key is missing, malformed, or revoked.

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 402 — The balance is empty. The lookup did not run.

```json
{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 404 — The database assigns no prefix to that number (`ASN_NOT_FOUND`). Nothing was charged.

```json
{
    "success": false,
    "error": {
        "code": "ASN_NOT_FOUND",
        "message": "No autonomous system numbered 999999 is in the index.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 429 — Over 5 requests per second for the key. Retry after the limit resets.

```json
{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 501 — The ASN prefix index has not been built on this server (`ASN_INDEX_UNAVAILABLE`). Nothing was charged.

```json
{
    "success": false,
    "error": {
        "code": "ASN_INDEX_UNAVAILABLE",
        "message": "The ASN prefix index has not been built on this server yet.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `INSUFFICIENT_CREDITS` — https://spaw.co/docs/errors/INSUFFICIENT_CREDITS
- `ASN_NOT_FOUND` — https://spaw.co/docs/errors/ASN_NOT_FOUND
- `ASN_INDEX_UNAVAILABLE` — https://spaw.co/docs/errors/ASN_INDEX_UNAVAILABLE
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/get-ip-asn · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api