Psychic

What is Psychic?

Psychic packages the GreyNoise Internet Scanner Intelligence dataset into a small, downloadable file that you query on your own systems. Instead of calling the GreyNoise API once per IP address, you download one file for a day or a rolling window, load it into your SIEM, data pipeline, or script, and look up IPs locally at memory speed.

Psychic is built for four situations where a per-IP API call does not fit:

• High volume. A SIEM or streaming pipeline handling tens of thousands of events per second.
• Query privacy. Lookups happen on your host. GreyNoise never sees which IPs you are checking.
• Offline or air-gapped environments. Download the file once, move it inside the boundary, and enrich events without outbound connectivity.
• Small footprint. Psychic compresses a full day of GreyNoise observations, typically around 800k-1.5 million IP addresses, into a file of about 2 MB for Model 1 and about 14 MB for Model 3.

Psychic is delivered through the GreyNoise API. There is no Visualizer interface for it today.

Prerequisites

• Your GreyNoise API key.

• A way to read the downloaded file: any MaxMind DB reader for .mmdb files, or the GreyNoise Python SDK for .bin files.

• Subscription access:

Choosing a model

Psychic offers three models. Each one builds on the previous one, so higher models carry more context and produce larger files.

Access to each model is set by your subscription. Requesting a model your plan does not include returns a 403 response.

Typical file sizes

Sizes vary with how much scanning activity GreyNoise observes on a given day.

The bin format stays small because it stores IPs as compressed bitmaps. The mmdb format is larger because it carries a search tree, but it opens with standard MaxMind tooling and needs no GreyNoise-specific code.

Choosing a file format

Set the format field in your request to one of:

• mmdb (recommended for most users). MaxMind DB format. Any MaxMind reader library can open it, and many SIEMs and data pipelines can load an MMDB file directly as a lookup table. Every observed IP is stored as a /32 record containing the fields for that model.
• bin (default when format is omitted). GreyNoise's compact binary format built on compressed bitmaps. It is the smallest and fastest to load, and it is what the GreyNoise Python SDK reads. Choose it when you are using the SDK or building your own high-throughput lookup service.

Downloading the latest daily model

A daily model contains all IPs GreyNoise observed on a single UTC calendar day. Files are regenerated every hour, so today's file grows through the day, and yesterday's file is finalized shortly after midnight UTC.

Send a POST request to https://api.greynoise.io/v1/psychic with your API key in the key header and a JSON body that names the model. Omitting date returns the latest daily file.

curl -X POST "https://api.greynoise.io/v1/psychic" \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "3", "format": "mmdb"}' \
  -OJ

The -OJ flags save the download using the filename GreyNoise suggests, for example m3-2026-09-23.mmdb.

Request body fields

Downloading a specific day

Set date to the day you want:

curl -X POST "https://api.greynoise.io/v1/psychic" \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "2", "date": "2026-09-15", "format": "mmdb"}' \
  -OJ

Downloading a multi-day window

Most SIEM use cases want "everything GreyNoise saw in the last week" rather than a single day. Psychic offers two ways to get that.

Rolling snapshots (7 or 30 days)

Snapshots are precomputed files covering the last 7 or 30 days, ending today (UTC). They are refreshed hourly and downloaded immediately, making them the fastest way to get a rolling window.

Send a POST request to https://api.greynoise.io/v1/psychic/snapshots:

curl -X POST "https://api.greynoise.io/v1/psychic/snapshots" \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "3", "days": 7, "format": "mmdb"}' \
  -OJ

The snapshot endpoint does not accept date, start_date, or end_date. The suggested filename includes the window, for example m3-2026-09-17-to-2026-09-23.mmdb.

Custom date range (up to 30 days)

For a window that is not 7 or 30 days, or one that does not end today, request a range from the model download endpoint:

curl -X POST "https://api.greynoise.io/v1/psychic" \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "3", "start_date": "2026-09-01", "end_date": "2026-09-14", "format": "mmdb"}' \
  -OJ

Range files are generated on demand the first time they are requested and cached afterward. A first request for a new range can take longer than a daily download. If GreyNoise is already generating many ranges, the request returns 429. Wait and retry.

How multi-day files combine data

In a snapshot or range file, an IP is present if GreyNoise observed it on any day in the window. Its date and last_seen fields hold the most recent day it was seen. Tags and CVEs are combined across all days. If an IP's classification changed during the window, benign takes precedence, then malicious, then suspicious. The actor is the most recently attributed one.

Looking up IPs in an MMDB file

Once downloaded, you can query the file with any MaxMind DB library. This Python example uses the maxminddb package:

import maxminddb

with maxminddb.open_database("m3-2026-09-23.mmdb") as reader:
    for ip in ["203.0.113.10", "198.51.100.7"]:
        record = reader.get(ip)
        if record is None:
            print(f"{ip}: not observed by GreyNoise")
            continue
        print(f"{ip}: {record['classification']}, tags={record.get('tags', [])}")

reader.get() returns None for any IP GreyNoise did not observe in the file's window. IPs that were observed return a record with the fields for your model:

Example Model 3 record:

{
  "date": "2026-09-23",
  "seen": true,
  "classification": "malicious",
  "handshake_complete": true,
  "last_seen": "2026-09-23T00:00:00Z",
  "actor": "unknown",
  "tags": ["SSH Bruteforcer", "Web Crawler"],
  "cves": ["CVE-2023-45318"]
}

Using the GreyNoise Python SDK and CLI

The GreyNoise Python SDK (version 3.1.0 or later) can download Psychic files, convert them to CSV, and run lookups directly against the .bin format.

pip3 install --upgrade greynoise
greynoise setup -k YOUR_API_KEY

# Download today's Model 3 file as MMDB
greynoise psychic-download --model 3 --format mmdb

# Download a specific day as CSV (one row per observed IP)
greynoise psychic-download --model 2 --format csv --date 2026-09-15

# Generate a custom range as a .bin file
greynoise psychic-generate --model 3 --start-date 2026-09-01 --end-date 2026-09-14

To look up IPs from the command line using a locally cached Psychic file instead of the API, enable Psychic and pass the --psychic flag to the ip command:

export GREYNOISE_PSYCHIC=true
export GREYNOISE_PSYCHIC_MODEL=3
greynoise ip --psychic 203.0.113.10

The SDK downloads today's file on first use, caches it locally, and refreshes it when the cache is more than 1 hour old. In Python:

from greynoise.api import GreyNoise, APIConfig

config = APIConfig(api_key="YOUR_API_KEY", psychic=True, psychic_model=3)
client = GreyNoise(config)
result = client.psychic_lookup("203.0.113.10")
print(result["classification"], result["tags"])

Keeping your copy current

Psychic files are regenerated every hour. To stay current, schedule a download at whatever interval matches how fresh you need the data to be. Many teams pull a 7-day snapshot hourly and automatically swap it into their lookup table. Each successful download counts as one use against your Psychic allowance for that model, so choose a cadence that fits your plan.

Limits

• IPv4 only. Psychic files do not include IPv6 addresses.
• UTC dates. All days, windows, and timestamps are in UTC.
• Range length. Custom ranges are limited to 30 days.
• Lookback. Historical dates and windows must fall within your subscription's lookback period.
• Usage. Each successful download counts against your Psychic allowance for that model.
• Request body. Requests must be JSON and no larger than 32 KiB.

Error responses

Error bodies are JSON with a single error field describing the problem.

Reach out to [email protected] for any questions or feedback.