# InternetData

> Licensed IP databases: VPN, proxy, hosting, Tor, relay and CDN address data, rebuilt daily
> and downloaded as files you query yourself. There is NO lookup API - nothing here answers
> a question about one address; you hold the database and answer it in your own infrastructure.

Site: https://internetdata.io
Docs: https://docs.internetdata.io
API:  https://internetdata.io/api/v2/database/

## Access

Granted by contract, one database family at a time, to an API key carrying the db.download
scope. Keys are default-deny. The key presents as a bearer token, as X-Api-Key, or as ?apikey=.

## The calls

- Catalog: GET /api/v2/database/list
- Metadata: GET /api/v2/database/metadata?id=
- Download: GET /api/v2/database/download?id=&format=
- Checksums: GET /api/v2/database/checksum?id=&format=
- History: GET /api/v2/database/downloads?limit=

```
# a 302 to object storage is the success case
curl -L -H "Authorization: Bearer $KEY" \
  "https://internetdata.io/api/v2/database/download?id=vpn_ip_v1&format=csvgz" \
  -o vpn_ip_v1.csv.gz

# and verify what landed
curl -s -H "X-Api-Key: $KEY" \
  "https://internetdata.io/api/v2/database/checksum?id=vpn_ip_v1&format=csvgz"
```

## What metadata returns

```json
GET /api/v2/database/metadata?id=vpn_ip_v1

{
  "id": "vpn_ip_v1",
  "update_freq": "daily",
  "updated": "2026-09-21",
  "entries": 17328905,
  "size": { "csvgz": 119755873,
            "mmdb": 575833040 },
  "schema": {
    "csvgz": [
      { "name": "start_ip", "type": "ipaddress" },
      …
    ]
  }
}
```

- id: The versioned id. This is what download, checksum and metadata take.
- update_freq: How often a new build is published. Daily for every database in the catalog.
- updated: The date the published build was generated. Fetch only when this moves.
- entries: Row count in the current build: ranges for a range database, not addresses.
- size: Bytes per format. A format absent here is not built for this database.
- schema: Columns keyed by format: name, type and description, in file order.
- sample: A few real rows, keyed by format, when the build carries them.

## Reading it correctly

- A 302 is the success case. Download answers a redirect to a time-limited link on object storage; the bytes never come through the API. Follow it (curl -L). The link authorizes the START of a transfer, so one already running is not interrupted when it lapses.
- Keys are default-deny. A key does not gain database access until db.download is added to it. Missing key, wrong key, missing scope and a key belonging to no organization all answer 401 with rc UNAUTHORIZED.
- 403 is a licensing answer, not an auth one. rc NOT_LICENSED means your organization never bought this family; LICENSE_EXPIRED means the term ended. Neither is retryable — it needs a contract, not a backoff.
- 503 means licensed but not published yet. rc NOT_AVAILABLE means the current build has not been published yet. Retry later; do not treat it as an error, and do not substitute a different database for it.
- Not every format exists for every database. csvgz for every database, mmdb for most. The provider catalogs are keyed by provider id, so there is nothing for an mmdb to index, and asking one for it is a 400 INVALID_FORMAT — a deliberate refusal, not a gap in coverage. list names the formats each version is built in.
- A license covers a family, a download names an id. list returns a family (base, e.g. vpn_ip) with your standing, and the id to pass onward to metadata and download. Read that id from list rather than composing it yourself.
- There is no address endpoint to call. No lookup API exists, by design — nothing here answers "is 45.83.91.1 a VPN". You license the database and answer that question inside your own infrastructure.

## Status codes

- 302 a download's success case: a time-limited link to object storage, which -L follows
- 400 INVALID_FORMAT: the database is not built in the format asked for
- 401 UNAUTHORIZED: no key, a wrong key, a key without db.download, or a key that belongs to no organization
- 403 NOT_LICENSED or LICENSE_EXPIRED: your organization never licensed this family, or its term has ended
- 404 UNKNOWN_DATASET: no database has that id
- 503 NOT_AVAILABLE: licensed, but the current build has not been published yet

## What a license lets you do (license_type, as list reports it)

- evaluation: A full current build for internal testing only, time-boxed and under NDA. Integrating it across a product or serving customer use cases with it needs written permission first.
- standard: Unlimited internal use: detection, decisions and operations inside your own product. The rows do not leave your walls.
- redistribute: The rows, or per-address answers derived from them, may reach your own customers, within the scope written into the contract.
- null: No license. Every family with standing unlicensed reports this, and download refuses with 403.

## Pages

- https://internetdata.io/ai-agents: this contract, in full, as a page
- https://internetdata.io/databases/vpn-ip: one page per database family, with its schema and real sample rows
- https://internetdata.io/pricing: the two licenses, Standard and Redistribution
- https://internetdata.io/scan: why you may see probes from our scanners, and how to opt out
- https://internetdata.io/terms, /privacy, /aup: the legal documents

## Caveat

Classifications are inferences from measurement, published operator data and public
registration records. They can be wrong or go stale. Do not make one the sole basis for
denying a person access to a service.