Skip to content
InternetData

Batch

post/batch

Up to 1000 addresses, AS numbers and domains in one call, each answered exactly as its own lookup would be and each counted as one lookup. Answers and failures are keyed by the string you sent, in the order you sent them; duplicates collapse. Needs a paid plan: a batch of one item is answered as the lookup it is on any plan.

Authorization (optional)

apiKeyQueryapikey in query

?apikey=<key>. Convenient in a browser; prefer a header elsewhere.

apiKeyHeaderX-Api-Key in header

X-Api-Key: <key>.

bearerAuthbearer token

Authorization: Bearer <key>.

Request body

application/json

ipsarray<string>

Addresses.

asnsarray<string>

AS numbers, AS15169 or 15169; a JSON number reads too.

domainsarray<string>

Domains.

Responses

200application/json

Every item, under results or errors.

resultsrequiredobject

Each answered item's lookup, keyed by the string sent.

errorsrequiredobject

Each failed item, keyed by the string sent.

TypeScript type
ts
{
  results: Record<string, {
    ip: string;
    is_bogon: boolean;
    is_vpn?: boolean;
    is_tor: boolean;
    is_relay: boolean;
    is_resproxy?: boolean;
    is_dcproxy?: boolean;
    is_mobproxy?: boolean;
    is_pubproxy?: boolean;
    is_hosting?: boolean;
    is_cdn?: boolean;
    is_anycast: boolean;
    is_carrier: boolean;
    is_satellite: boolean;
    is_ssh: boolean;
    is_smtp: boolean;
    is_web: boolean;
    is_dns_resolver: boolean;
    is_bittorrent: boolean;
    vpn?: {
      provider?: string;
      provider_name?: string;
      confidence?: string;
      last_seen?: string;
    };
    tor: {
      provider?: string;
      provider_name?: string;
      confidence?: string;
      last_seen?: string;
    };
    relay: {
      provider?: string;
      provider_name?: string;
      confidence?: string;
      last_seen?: string;
    };
    resproxy?: {
      provider?: string;
      provider_name?: string;
      first_seen?: string;
      last_seen?: string;
      hits?: number;
      hits_days_pct?: number;
      providers_num?: number;
    };
    dcproxy?: {
      provider?: string;
      provider_name?: string;
      first_seen?: string;
      last_seen?: string;
      hits?: number;
      hits_days_pct?: number;
      providers_num?: number;
    };
    mobproxy?: {
      provider?: string;
      provider_name?: string;
      first_seen?: string;
      last_seen?: string;
      hits?: number;
      hits_days_pct?: number;
      providers_num?: number;
    };
    pubproxy?: {
      entry?: boolean;
      exit?: boolean;
      protocols?: string[];
      num_ports?: number;
      num_proxies?: number;
      last_seen?: string;
      last_usable?: string;
    };
    hosting?: {
      provider?: string;
      provider_name?: string;
      confidence?: string;
      last_seen?: string;
    };
    cdn?: {
      provider?: string;
      provider_name?: string;
      confidence?: string;
      last_seen?: string;
    };
    carrier?: {
      name?: string;
      mcc?: string;
      mnc?: string;
      country?: string;
      confidence?: string;
    };
    satellite?: {
      provider?: string;
      provider_name?: string;
      orbit?: string;
      segment?: string;
      country?: string;
      asn?: number;
      confidence?: string;
    };
    ssh?: {
      port?: number;
      banner?: string;
      host_key_fp?: string;
      session_ok?: boolean;
      first_seen?: string;
      last_seen?: string;
    };
    smtp?: {
      port?: number;
      banner?: string;
      session_ok?: boolean;
      first_seen?: string;
      last_seen?: string;
    };
    web?: {
      port: number;
      tls_ok: boolean;
      session_ok: boolean;
      status_code: number;
      server: string;
      location: string;
      title: string;
      cert_subject_cn: string;
      cert_subject_o: string;
      cert_issuer_dn: string;
      cert_browser_trusted: boolean;
      tls_version: string;
      first_seen: string;
      last_seen: string;
    }[];
    dns_resolver?: {
      port?: number;
      recursion_available?: boolean;
      rcode?: number;
      answer_correct?: boolean;
      first_seen?: string;
      last_seen?: string;
    };
    bittorrent?: {
      verified?: boolean;
      id_matches_ip?: boolean;
      first_seen?: string;
      last_seen?: string;
      last_reachable?: string;
      days_seen?: number;
      num_ports?: number;
      peak_num_ports?: number;
      indexer?: boolean;
      clients?: string[];
    };
    location: {
      continent: string;
      continent_name: string;
      country: string;
      country_name: string;
      timezone: string;
      currency_code: string;
      currency_name: string;
      currency_symbol: string;
      flag_emoji: string;
      flag_unicode: string;
      region?: string;
      region_code?: string;
      city?: string;
      postal_code?: string;
      latitude?: number;
      longitude?: number;
      accuracy_radius?: number;
      geoname_id?: string;
      dma_code?: string;
      last_changed?: string;
    };
    asn: {
      asn: number;
      name: string;
      domain: string;
      type: string;
      prefix: string;
      country?: string;
      rpki_status?: string;
    };
    company: {
      name: string;
      domain: string;
      type?: string;
      country?: string;
    };
    hostname: string;
    abuse: {
      email: string;
      name?: string;
      phone?: string;
      address?: string;
      country?: string;
      network?: string;
      validated?: boolean;
      unvalidated_since?: string;
    };
    whois?: {
      id: string;
      name: string;
      org: string;
      country: string;
      status: string;
      source: string;
      domain: string;
      abuse_email: string;
      asn: number;
    };
    rwhois?: {
      id: string;
      name: string;
      country: string;
      source: string;
      domain: string;
      abuse_email: string;
    };
    hosted_domains?: {
      total: number;
    };
    trial_expired?: boolean;
  } | {
    asn: number;
    name: string;
    country: string;
    registry: string;
    allocated: string;
    domain: string;
    type?: string;
    num_ips?: number;
    num_prefixes4?: number;
    num_prefixes6?: number;
    rpki_valid?: number;
    rpki_invalid?: number;
    rpki_not_found?: number;
    whois?: Record<string, string>;
    prefixes?: {
      prefix: string;
      peer_count: number;
      rpki_status: string;
      first_seen: string;
      country: string;
      size: number;
      other_origins: number[];
    }[];
    trial_expired?: boolean;
  } | {
    domain: string;
    is_registered: boolean;
    is_disposable?: boolean;
    has_a: boolean;
    has_aaaa: boolean;
    has_mx: boolean;
    has_ns: boolean;
    has_cname: boolean;
    dns?: {
      a: {
        ip: string;
        last_seen: string;
      }[];
      aaaa: {
        ip: string;
        last_seen: string;
      }[];
      mx: {
        priority: number;
        host: string;
        last_seen: string;
      }[];
      ns: {
        host: string;
        last_seen: string;
      }[];
      cname: {
        target: string;
        last_seen: string;
      }[];
    };
    ip_ranges?: {
      domain: string;
      redirects_to: string;
      total: number;
      ipv4: number;
      ranges: {
        range: string;
        name: string;
        country: string;
      }[];
    };
    disposable?: {
      confidence?: string;
      providers?: string[];
      first_seen?: string;
      last_seen?: string;
    };
    trial_expired?: boolean;
  }>;
  errors: Record<string, {
    status: number;
    error: string;
  }>;
}
400application/json

The body is not a batch, or holds no items or more than 1000.

errorrequiredstring

What went wrong.

TypeScript type
ts
{
  error: string;
}
401application/json

No key, or a key that does not work.

errorrequiredstring

What went wrong.

TypeScript type
ts
{
  error: string;
}
402application/json

A key on the free plan.

errorrequiredstring

What went wrong.

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

The key may not be used from this address, lacks the ip.lookup scope (Lookups, in the console's API keys), or was sent over plain HTTP.

errorrequiredstring

What went wrong.

TypeScript type
ts
{
  error: string;
}
413application/json

The body is larger than 512 KB.

errorrequiredstring

What went wrong.

TypeScript type
ts
{
  error: string;
}
429application/json

A rate limit; retry after Retry-After.

errorrequiredstring

What went wrong.

TypeScript type
ts
{
  error: string;
}