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

# IP Lookup

> Look up intelligence about an IP address — geolocation, VPN/proxy/Tor detection (with named provider), ASN, company, timezone, abuse reports, malware analysis, scanner classification, open ports & CVEs (Shodan InternetDB + Censys), crt.sh certificate transparency, PeeringDB operator/IXP context, proxy/fraud second opinions, extra threat-intel feeds, passive DNS history, reputation over time, routing/allocation history, TLS/JARM fingerprints, honeypot and C2 detection.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="ip" type="string" required>
  The IP address to look up (IPv4 or IPv6).
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL (API Key) theme={"dark"}
  curl -X POST "https://encrata.com/api/agent/ip" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ip": "8.8.8.8"}'
  ```

  ```python Python theme={"dark"}
  from encrata import Encrata

  client = Encrata("YOUR_API_KEY")
  ip_info = client.ip_lookup("8.8.8.8")

  print(ip_info.location.country)  # "United States"
  print(ip_info.security.is_vpn)   # False
  print(ip_info.company.name)      # "Google LLC"
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch("https://encrata.com/api/agent/ip", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ ip: "8.8.8.8" }),
  });
  const data = await resp.json();
  ```

  ```go Go theme={"dark"}
  body := `{"ip": "8.8.8.8"}`
  req, _ := http.NewRequest("POST", "https://encrata.com/api/agent/ip",
      strings.NewReader(body))
  req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")
  resp, _ := http.DefaultClient.Do(req)
  ```
</CodeGroup>

## Response

<ResponseField name="ip_address" type="string">
  The IP address that was looked up.
</ResponseField>

<ResponseField name="reverse_dns" type="string">
  The PTR (reverse DNS) record for the IP, if one exists.
</ResponseField>

<ResponseField name="security" type="object">
  Security/threat detection flags.

  <Expandable title="security fields">
    <ResponseField name="is_vpn" type="boolean">
      Whether the IP is a known VPN exit node.
    </ResponseField>

    <ResponseField name="is_proxy" type="boolean">
      Whether the IP is a known proxy server.
    </ResponseField>

    <ResponseField name="is_tor" type="boolean">
      Whether the IP is a Tor exit node.
    </ResponseField>

    <ResponseField name="is_hosting" type="boolean">
      Whether the IP belongs to a hosting/data center provider.
    </ResponseField>

    <ResponseField name="is_relay" type="boolean">
      Whether the IP is a known relay (e.g. iCloud Private Relay).
    </ResponseField>

    <ResponseField name="is_mobile" type="boolean">
      Whether the IP is from a mobile carrier.
    </ResponseField>

    <ResponseField name="is_abuse" type="boolean">
      Whether the IP has been flagged for abuse.
    </ResponseField>

    <ResponseField name="is_static" type="boolean">
      Whether the IP appears to be statically assigned (inferred from reverse DNS).
    </ResponseField>

    <ResponseField name="connection_type" type="string">
      Inferred connection type — `"hosting"`, `"mobile"`, `"residential"`, or `"business"`.
    </ResponseField>

    <ResponseField name="provider_name" type="string">
      Named VPN/proxy/Tor operator when one can be identified (e.g. `"NordVPN"`, `"Mullvad"`, `"Bright Data"`).
    </ResponseField>

    <ResponseField name="provider_type" type="string">
      Provider category — `"vpn"`, `"residential_proxy"`, `"datacenter_proxy"`, or `"tor"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="asn" type="object">
  Autonomous System Number details.

  <Expandable title="asn fields">
    <ResponseField name="asn" type="number">
      The AS number (e.g. `15169`).
    </ResponseField>

    <ResponseField name="name" type="string">
      ASN organization name (e.g. `"GOOGLE"`).
    </ResponseField>

    <ResponseField name="domain" type="string">
      Domain associated with the ASN.
    </ResponseField>

    <ResponseField name="type" type="string">
      ASN type — `"isp"`, `"hosting"`, `"business"`, or `"education"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company" type="object">
  Company or organization that owns the IP range.

  <Expandable title="company fields">
    <ResponseField name="name" type="string">
      Company name (e.g. `"Google LLC"`).
    </ResponseField>

    <ResponseField name="domain" type="string">
      Company domain.
    </ResponseField>

    <ResponseField name="type" type="string">
      Company type — `"isp"`, `"hosting"`, `"business"`, or `"education"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="location" type="object">
  Geolocation data.

  <Expandable title="location fields">
    <ResponseField name="city" type="string">
      City name.
    </ResponseField>

    <ResponseField name="region" type="string">
      Region/state name.
    </ResponseField>

    <ResponseField name="country" type="string">
      Full country name.
    </ResponseField>

    <ResponseField name="country_code" type="string">
      ISO 3166-1 alpha-2 country code.
    </ResponseField>

    <ResponseField name="postal_code" type="string">
      Postal/ZIP code.
    </ResponseField>

    <ResponseField name="continent" type="string">
      Continent name.
    </ResponseField>

    <ResponseField name="longitude" type="number">
      Longitude coordinate.
    </ResponseField>

    <ResponseField name="latitude" type="number">
      Latitude coordinate.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timezone" type="object">
  Timezone information.

  <Expandable title="timezone fields">
    <ResponseField name="name" type="string">
      IANA timezone name (e.g. `"America/Los_Angeles"`).
    </ResponseField>

    <ResponseField name="abbreviation" type="string">
      Timezone abbreviation (e.g. `"PDT"`).
    </ResponseField>

    <ResponseField name="utc_offset" type="number">
      UTC offset in hours (e.g. `-7`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="threat" type="object">
  Threat intelligence data.

  <Expandable title="threat fields">
    <ResponseField name="abuse_score" type="number">Abuse confidence score (0–100).</ResponseField>
    <ResponseField name="total_reports" type="number">Total abuse reports filed.</ResponseField>
    <ResponseField name="last_reported_at" type="string">ISO 8601 timestamp of last report.</ResponseField>
    <ResponseField name="usage_type" type="string">IP usage classification.</ResponseField>
    <ResponseField name="is_tor" type="boolean">Known Tor exit node.</ResponseField>
    <ResponseField name="is_whitelisted" type="boolean">Whitelisted as a known safe address.</ResponseField>
    <ResponseField name="distinct_users" type="number">Distinct reporters.</ResponseField>
    <ResponseField name="is_scanner" type="boolean">Observed scanning the internet.</ResponseField>
    <ResponseField name="is_known_service" type="boolean">Known benign service (e.g. search engine crawler, CDN).</ResponseField>
    <ResponseField name="classification" type="string">`"malicious"`, `"benign"`, or `"unknown"`.</ResponseField>
    <ResponseField name="scanner_name" type="string">Identified scanner/service name.</ResponseField>
    <ResponseField name="last_seen" type="string">Last seen date (YYYY-MM-DD).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="malware" type="object">
  Malware analysis results.

  <Expandable title="malware fields">
    <ResponseField name="malicious_count" type="number">Vendors flagging as malicious.</ResponseField>
    <ResponseField name="suspicious_count" type="number">Vendors flagging as suspicious.</ResponseField>
    <ResponseField name="harmless_count" type="number">Vendors classifying as harmless.</ResponseField>
    <ResponseField name="undetected_count" type="number">Vendors with no opinion.</ResponseField>
    <ResponseField name="reputation" type="number">Community reputation score.</ResponseField>
    <ResponseField name="network" type="string">CIDR network range.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="network" type="object">
  Network allocation / WHOIS data from RDAP (free, no API key).

  <Expandable title="network fields">
    <ResponseField name="cidr" type="string">Allocated CIDR block (e.g. `"8.8.8.0/24"`).</ResponseField>
    <ResponseField name="range_start" type="string">First IP in the allocated range.</ResponseField>
    <ResponseField name="range_end" type="string">Last IP in the allocated range.</ResponseField>
    <ResponseField name="name" type="string">Network/allocation name.</ResponseField>
    <ResponseField name="rir" type="string">Regional Internet Registry — `"ARIN"`, `"RIPE"`, `"APNIC"`, `"LACNIC"`, or `"AFRINIC"`.</ResponseField>
    <ResponseField name="registrant_org" type="string">Organization the range is registered to.</ResponseField>
    <ResponseField name="abuse_email" type="string">Abuse contact email.</ResponseField>
    <ResponseField name="abuse_phone" type="string">Abuse contact phone number.</ResponseField>
    <ResponseField name="allocated_at" type="string">Allocation/registration date.</ResponseField>
    <ResponseField name="country" type="string">Registered country code.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ports" type="object">
  Open ports and exposed services from Shodan InternetDB and Censys (Censys requires a key).

  <Expandable title="ports fields">
    <ResponseField name="ports" type="number[]">List of open TCP ports (union of Shodan + Censys).</ResponseField>
    <ResponseField name="services" type="object[]">Per-port service labels — `{ port, service, banner }` (e.g. `{ "port": 443, "service": "HTTPS" }`).</ResponseField>
    <ResponseField name="software" type="string[]">Detected software (CPE identifiers).</ResponseField>
    <ResponseField name="vulns" type="string[]">Known CVE identifiers affecting the host.</ResponseField>
    <ResponseField name="tags" type="string[]">Shodan classification tags (e.g. `"cdn"`, `"cloud"`).</ResponseField>
    <ResponseField name="hostnames" type="string[]">Hostnames associated with the IP.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="blocklist" type="object">
  Spam/abuse blocklist (DNSBL) membership.

  <Expandable title="blocklist fields">
    <ResponseField name="listed" type="boolean">Whether the IP is listed on any blocklist.</ResponseField>
    <ResponseField name="lists" type="string[]">Names of blocklists the IP appears on (e.g. Spamhaus, SpamCop, Barracuda, SORBS).</ResponseField>
    <ResponseField name="checked" type="number">Number of blocklists queried.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cloud" type="object">
  Detected cloud hosting provider.

  <Expandable title="cloud fields">
    <ResponseField name="is_cloud" type="boolean">Whether the IP is hosted on a cloud provider.</ResponseField>
    <ResponseField name="provider" type="string">Cloud provider name (e.g. `"AWS"`, `"Google Cloud"`, `"Azure"`, `"Cloudflare"`).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="bgp" type="object">
  BGP routing data from RIPEstat (free, no API key).

  <Expandable title="bgp fields">
    <ResponseField name="prefix" type="string">Announced BGP prefix covering the IP.</ResponseField>
    <ResponseField name="announced" type="boolean">Whether the prefix is currently announced.</ResponseField>
    <ResponseField name="upstreams" type="string[]">Upstream (provider) ASNs.</ResponseField>
    <ResponseField name="peers" type="string[]">Peer ASNs.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="passive_dns" type="object">
  History of domains that have resolved to this IP.

  <Expandable title="passive_dns fields">
    <ResponseField name="records" type="object[]">Domain history — each entry has `domain`, `record_type`, `first_seen`, `last_seen`, and `source`.</ResponseField>
    <ResponseField name="total_count" type="number">Total number of distinct domains observed on the IP.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reputation_history" type="object">
  The IP's reputation tracked over time — a timeline rather than a single snapshot. Grows on each lookup.

  <Expandable title="reputation_history fields">
    <ResponseField name="snapshots" type="object[]">Time-ordered snapshots — each has `date`, `abuse_score`, `malicious_count`, `listed`, `is_c2`, `classification`, and `threat_level` (`clean` | `low` | `medium` | `high` | `critical`).</ResponseField>
    <ResponseField name="trend" type="string">Overall direction — `"improving"`, `"worsening"`, or `"stable"`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="routing_history" type="object">
  Allocation and BGP-announcement history — who has originated the IP over time, with hijack detection.

  <Expandable title="routing_history fields">
    <ResponseField name="entries" type="object[]">Origin windows — each has `asn`, `holder`, `prefix`, `start_time`, and `end_time`.</ResponseField>
    <ResponseField name="origin_changes" type="number">Number of distinct origin ASNs observed over time.</ResponseField>
    <ResponseField name="possible_hijack" type="boolean">Whether overlapping or rapidly changing origins suggest a possible BGP hijack.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tls" type="object">
  Active TLS/certificate fingerprint from a live probe of port 443. Use the JARM hash and certificate SHA-256 to pivot to related infrastructure.

  <Expandable title="tls fields">
    <ResponseField name="probed" type="boolean">Whether a live TLS probe was attempted.</ResponseField>
    <ResponseField name="has_tls" type="boolean">Whether the host completed a TLS handshake.</ResponseField>
    <ResponseField name="jarm" type="string">62-character JARM server fingerprint.</ResponseField>
    <ResponseField name="ja3s" type="string">JA3S hash of the negotiated server parameters.</ResponseField>
    <ResponseField name="tls_version" type="string">Negotiated TLS version (e.g. `"TLS 1.3"`).</ResponseField>
    <ResponseField name="cipher_suite" type="string">Negotiated cipher suite.</ResponseField>
    <ResponseField name="certificate" type="object">Leaf certificate — `subject_cn`, `issuer_cn`, `sans[]`, `not_before`, `not_after`, `serial`, `sha256`, `key_algorithm`, `self_signed`, and `expired`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="c2" type="object">
  Command-and-control / botnet detection.

  <Expandable title="c2 fields">
    <ResponseField name="is_c2" type="boolean">Whether the IP is a known malware C2 / botnet controller.</ResponseField>
    <ResponseField name="malware" type="string">Associated malware family, if known.</ResponseField>
    <ResponseField name="botnet" type="string">Associated botnet, if known.</ResponseField>
    <ResponseField name="first_seen" type="string">When the IP was first seen as C2.</ResponseField>
    <ResponseField name="last_seen" type="string">When the IP was last seen as C2.</ResponseField>
    <ResponseField name="confidence" type="string">Detection confidence — `"low"`, `"medium"`, or `"high"`.</ResponseField>
    <ResponseField name="source" type="string">Feed the detection came from.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="honeypot" type="object">
  Honeypot / decoy detection.

  <Expandable title="honeypot fields">
    <ResponseField name="is_honeypot" type="boolean">Whether the IP is likely a honeypot/decoy.</ResponseField>
    <ResponseField name="confidence" type="string">Detection confidence — `"low"`, `"medium"`, or `"high"`.</ResponseField>
    <ResponseField name="reason" type="string">Why it was flagged.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="certificates" type="object">
  Certificate transparency records that reference the IP, from crt.sh (free, no API key).

  <Expandable title="certificates fields">
    <ResponseField name="total" type="number">Total certificate-transparency records found.</ResponseField>
    <ResponseField name="domains" type="string[]">Unique names (CN/SAN) seen across the certificates.</ResponseField>
    <ResponseField name="recent" type="object[]">Most recent certificates — each has `common_name`, `names[]`, `issuer`, `not_before`, `not_after`, and `serial_number`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="peering" type="object">
  Operator and Internet Exchange (IXP) context from PeeringDB (free, no API key).

  <Expandable title="peering fields">
    <ResponseField name="asn" type="number">Origin AS number resolved for the IP.</ResponseField>
    <ResponseField name="org_name" type="string">Operator organization name.</ResponseField>
    <ResponseField name="network_name" type="string">PeeringDB network name.</ResponseField>
    <ResponseField name="info_type" type="string">Network type — e.g. `"NSP"`, `"Content"`, `"Cable/DSL/ISP"`.</ResponseField>
    <ResponseField name="traffic" type="string">Estimated traffic level.</ResponseField>
    <ResponseField name="website" type="string">Operator website.</ResponseField>
    <ResponseField name="ixps" type="string[]">Internet exchanges the network is present at.</ResponseField>
    <ResponseField name="ix_count" type="number">Number of IX presences.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fraud" type="object">
  Proxy/fraud "second opinions" — independent verdicts from multiple providers (proxycheck.io is keyless; IPQualityScore, Spur, Scamalytics, and IPHub require keys).

  <Expandable title="fraud fields">
    <ResponseField name="scores" type="object[]">One entry per provider — each has `source` (`"proxycheck.io"`, `"ipqualityscore"`, `"scamalytics"`, `"iphub"`, `"spur"`), `score` (0–100), `risk` (`low` | `medium` | `high` | `critical`), `is_proxy`, `is_vpn`, `is_tor`, `type`, and `detail`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="threat_feeds" type="object">
  Extra threat-intelligence feeds (require keys): AlienVault OTX and Pulsedive.

  <Expandable title="threat_feeds fields">
    <ResponseField name="feeds" type="object[]">One entry per feed — each has `source` (`"alienvault_otx"`, `"pulsedive"`), `malicious`, `score`, `risk` (`none` | `low` | `medium` | `high` | `critical`), `pulses` (OTX), and `categories[]`.</ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json 200 OK theme={"dark"}
{
  "ip_address": "8.8.8.8",
  "reverse_dns": "dns.google",
  "security": {
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_hosting": true,
    "is_relay": false,
    "is_mobile": false,
    "is_abuse": false,
    "is_static": true,
    "connection_type": "hosting"
  },
  "asn": {
    "asn": 15169,
    "name": "GOOGLE",
    "domain": "google.com",
    "type": "hosting"
  },
  "company": {
    "name": "Google LLC",
    "domain": "google.com",
    "type": "hosting"
  },
  "location": {
    "city": "Mountain View",
    "region": "California",
    "country": "United States",
    "country_code": "US",
    "postal_code": "94043",
    "continent": "North America",
    "longitude": -122.0775,
    "latitude": 37.4056
  },
  "timezone": {
    "name": "America/Los_Angeles",
    "abbreviation": "PDT",
    "utc_offset": -7
  },
  "threat": {
    "abuse_score": 0,
    "total_reports": 87,
    "last_reported_at": "2026-05-10T14:22:00+00:00",
    "usage_type": "Data Center/Web Hosting/Transit",
    "is_tor": false,
    "is_whitelisted": true,
    "distinct_users": 42,
    "is_scanner": false,
    "is_known_service": true,
    "classification": "benign",
    "scanner_name": "Google DNS",
    "last_seen": "2026-05-11"
  },
  "malware": {
    "malicious_count": 0,
    "suspicious_count": 0,
    "harmless_count": 74,
    "undetected_count": 12,
    "reputation": 30,
    "network": "8.8.8.0/24"
  },
  "network": {
    "cidr": "8.8.8.0/24",
    "range_start": "8.8.8.0",
    "range_end": "8.8.8.255",
    "name": "GOGL",
    "rir": "ARIN",
    "registrant_org": "Google LLC",
    "abuse_email": "network-abuse@google.com",
    "allocated_at": "2014-03-14",
    "country": "US"
  },
  "ports": {
    "ports": [53, 443],
    "software": ["cpe:/a:google:dns"],
    "vulns": [],
    "tags": ["cdn"],
    "hostnames": ["dns.google"]
  },
  "blocklist": {
    "listed": false,
    "lists": [],
    "checked": 5
  },
  "cloud": {
    "is_cloud": true,
    "provider": "Google Cloud"
  },
  "bgp": {
    "prefix": "8.8.8.0/24",
    "announced": true,
    "upstreams": ["15169"],
    "peers": ["1299", "3356"]
  },
  "passive_dns": {
    "records": [
      { "domain": "dns.google", "record_type": "A", "first_seen": "2018-04-02", "last_seen": "2026-06-24", "source": "pdns" }
    ],
    "total_count": 1
  },
  "reputation_history": {
    "snapshots": [
      { "date": "2026-06-20", "abuse_score": 0, "malicious_count": 0, "listed": false, "is_c2": false, "classification": "benign", "threat_level": "clean" }
    ],
    "trend": "stable"
  },
  "routing_history": {
    "entries": [
      { "asn": 15169, "holder": "GOOGLE", "prefix": "8.8.8.0/24", "start_time": "2014-03-14", "end_time": "" }
    ],
    "origin_changes": 0,
    "possible_hijack": false
  },
  "tls": {
    "probed": true,
    "has_tls": true,
    "jarm": "27d40d40d29d40d1dc42d43d00041d4689ee210389f4f6b4b5b1b93f92252d",
    "tls_version": "TLS 1.3",
    "cipher_suite": "TLS_AES_256_GCM_SHA384",
    "certificate": {
      "subject_cn": "dns.google",
      "issuer_cn": "WR2",
      "sans": ["dns.google", "*.dns.google.com"],
      "not_after": "2026-08-18",
      "sha256": "a1b2c3...",
      "self_signed": false,
      "expired": false
    }
  },
  "c2": { "is_c2": false },
  "honeypot": { "is_honeypot": false },
  "certificates": {
    "total": 3,
    "domains": ["dns.google", "*.dns.google.com"],
    "recent": [
      { "common_name": "dns.google", "issuer": "WR2", "not_before": "2026-05-20", "not_after": "2026-08-18" }
    ]
  },
  "peering": {
    "asn": 15169,
    "org_name": "Google LLC",
    "network_name": "Google",
    "info_type": "Content",
    "traffic": "100+ Tbps",
    "website": "https://about.google",
    "ixps": ["DE-CIX Frankfurt", "AMS-IX", "LINX LON1"],
    "ix_count": 3
  },
  "fraud": {
    "scores": [
      { "source": "proxycheck.io", "score": 0, "risk": "low", "is_proxy": false, "is_vpn": false, "is_tor": false, "type": "Business" }
    ]
  },
  "threat_feeds": {
    "feeds": [
      { "source": "alienvault_otx", "malicious": false, "risk": "none", "pulses": 0 }
    ]
  }
}
```

## Notes

* This endpoint is **free** — no credits are deducted.
* Supports both IPv4 and IPv6 addresses.
* Results are cached — repeat lookups within the cache window are instant.
* If a provider is unavailable, the response still includes data from the remaining providers.
* Several sources are **free / no API key** (Shodan InternetDB, crt.sh, PeeringDB, GreyNoise community, proxycheck.io free tier). Others are enriched only when their API key is configured server-side (Censys, IPQualityScore, Spur, Scamalytics, IPHub, AlienVault OTX, Pulsedive) — fields like `fraud`, `threat_feeds`, `certificates`, and `peering` are omitted when no provider returns data.
* Rate limited to **60 requests per minute**.