Skip to content
InternetData

Metadata

get/api/v2/database/metadata

Poll this to decide whether today's build is worth fetching: it carries updated and entries without downloading anything.

No format parameter - one document describes every format the database is built in. Needs no license: it answers for every database list returns, whatever its standing.

Authorization

ApiKeyQueryAuthapikey in query

?apikey=<key>. Convenient in a browser or a curl one-liner, which is how a database is usually fetched; prefer a header elsewhere.

This is the same v2 key as the other two schemes. A v1 credential is a different vocabulary and fails validation here, as it would anywhere.

ApiKeyHeaderAuthX-Api-Key in header

X-Api-Key: <key>. The same v2 key, for clients that do not set a bearer.

BearerAuthbearer token

Authorization: Bearer <key>, with a key from the console. Keys are default-deny: each operation names the scope it needs, and an existing key does not gain an operation until that scope is added to it.

Query parameters

idrequiredstring

Database identifier (e.g. vpn_ip_v1, resproxy_provider_v1).

Match ^[a-zA-Z0-9_]+$ · Example vpn_ip_v1

Responses

200application/json

OK

idrequiredstring
update_freqstring

How often a new build is published.

updatedrequiredstring (date)

ISO-8601 date (YYYY-MM-DD) the published build was generated on.

Example 2026-09-04

entriesrequiredinteger (int64)

Row count in the current build.

schemarequiredobject

Columns, keyed by format.

sampleobject

A few real rows, keyed by format.

sizerequiredobject

Bytes per format.

sample_sizeobject

Bytes per format of the evaluation sample, where one is published.

sample_entriesinteger

Row count in the evaluation sample.

TypeScript type
ts
{
  id: string;
  update_freq?: string;
  updated: string;
  entries: number;
  schema: Record<string, {
    name: string;
    type: string;
    description?: string;
  }[]>;
  sample?: Record<string, Record<string, unknown>[]>;
  size: Record<string, number>;
  sample_size?: Record<string, number>;
  sample_entries?: number;
}
401application/json

Missing, invalid, revoked or expired key; the key lacks the db.download scope; or the key belongs to no active organization. Each answers the same. rc: UNAUTHORIZED.

rcrequiredstring

A machine-readable result code. Deliberately not an enum: a code added later must stay parseable by a client generated today.

TypeScript type
ts
{
  rc: string;
}
403application/json

The request comes from an address outside the key's or its organization's allowed addresses. Change the allowlist or call from an allowed address: the key itself is fine. rc: IP_NOT_ALLOWED.

rcrequiredstring

A machine-readable result code. Deliberately not an enum: a code added later must stay parseable by a client generated today.

TypeScript type
ts
{
  rc: string;
}
404application/json

No such database. rc: UNKNOWN_DATASET.

rcrequiredstring

A machine-readable result code. Deliberately not an enum: a code added later must stay parseable by a client generated today.

TypeScript type
ts
{
  rc: string;
}
503application/json

The current build has not been published yet. rc: NOT_AVAILABLE.

rcrequiredstring

A machine-readable result code. Deliberately not an enum: a code added later must stay parseable by a client generated today.

TypeScript type
ts
{
  rc: string;
}