GreyNoise
Guides
Start typing to search…

Using the GreyNoise v3 API

This document is updated to match recommendations based on the v3 GreyNoise API.

API Information

  • API Address: api.greynoise.io
  • Requires an active Subscription or Enterprise Trial to Access

GreyNoise API Fundamentals

While typical to use, usage of GreyNoise REST API should follow these fundamental rules, based on the use case or intended usage:

  • Use the GreyNoise SDK when possible
  • For High-Volume usage, use the Multi-Lookup API endpoints.

PostMan Collection

The Full Set of API endpoints and parameters can be referenced here:

View in Postman

Basic IP Lookup

  • A basic IP lookup can be done in one of the following flavors:
    • Quick - this allows for a fast lookup with a small response payload that provides basic information on if the IP is found in one of the GreyNoise datasets, and additional information from each dataset, like classification or trust level.
    • Full - this allows for a lookup with a complete response of all data from all datasets available for a given IP address.
from greynoise.api import GreyNoise, APIConfig

api_config = APIConfig(api_key="api-key", integration_name="sdk-sample")
session = GreyNoise(api_config)
ip_address = "64.39.104.22"
output = []

quick_response = session.quick(ip_address)

print(quick_response)

from greynoise.api import GreyNoise, APIConfig

api_config = APIConfig(api_key="api-key", integration_name="sdk-sample")
session = GreyNoise(api_config)
ip_address = '64.39.104.22'
output = []

ip_response = session.ip(ip_address)

print(ip_response)

import requests

headers = {"key": "<api-key>", "Accept": "application/json"}

quick_url = "https://api.greynoise.io/v3/ip/"

ip_address = "64.39.104.22"
output = {}

quick_response = requests.get(quick_url + f"{ip_address}?quick=true", headers=headers)
quick_json = quick_response.json()

print(quick_json)

import requests

headers = {"key": "<api-key>", "Accept": "application/json"}

quick_url = "https://api.greynoise.io/v3/ip/"

ip_address = "64.39.104.22"
output = {}

ip_response = requests.get(quick_url + ip_address, headers=headers)
ip_json = ip_response.json()

print(ip_json)

Here is a response Sample from both the Quick and Full APIs. Some fields may be empty in the response based on the level of access of the account being used:

{
  "ip": "64.39.104.22",
  "business_service_intelligence": {
    "found": true,
    "trust_level": "1"
  },
  "internet_scanner_intelligence": {
    "found": true,
    "classification": "benign"
  },
  "request_metadata": {
    "restricted_fields": []
  }
}
{
  "ip": "64.39.104.22",
  "business_service_intelligence": {
    "found": true,
    "category": "vulnerability_management",
    "name": "Qualys",
    "description": "Qualys Inc (Qualys) is a provider of cloud-based platform information security and compliance cloud solutions. The company's cloud platform offers private cloud platforms, private cloud platform appliances, public cloud integrations, and cloud agents.",
    "explanation": "Vulnerability management services scan for and track software vulnerabilities. Traffic originating from Qualys may appear to be malicious but it is deliberately trying to identify and remediate vulnerabilities.",
    "last_updated": "2025-08-06T13:10:58Z",
    "reference": "https://www.qualys.com/",
    "trust_level": "1"
  },
  "internet_scanner_intelligence": {
    "first_seen": "2025-05-25",
    "last_seen": "2025-05-25",
    "found": true,
    "tags": [
      {
        "id": "b2cb0f57-9840-4ea7-b403-4899186e259d",
        "slug": "qualys",
        "name": "Qualys",
        "description": "IP addresses with this tag belong to Qualys Inc, a vulnerability management software company.",
        "category": "actor",
        "intention": "benign",
        "references": [
          "https://www.qualys.com/"
        ],
        "cves": [],
        "recommend_block": false,
        "created": "2020-04-07",
        "updated_at": "2025-08-05T22:54:10.464675Z"
      }
    ],
    "actor": "Qualys",
    "spoofable": true,
    "classification": "benign",
    "cves": [],
    "bot": false,
    "vpn": false,
    "vpn_service": "",
    "tor": false,
    "metadata": {
      "asn": "AS27385",
      "source_country": "United States",
      "source_country_code": "US",
      "source_city": "San Jose",
      "domain": "qualys.com",
      "rdns_parent": "",
      "rdns_validated": false,
      "organization": "QUALYS, Inc.",
      "category": "business",
      "rdns": "",
      "os": "",
      "sensor_count": 1,
      "sensor_hits": 2,
      "region": "California",
      "mobile": false,
      "single_destination": true,
      "destination_countries": [
        "Spain"
      ],
      "destination_country_codes": [
        "ES"
      ],
      "destination_asns": [
        "AS174"
      ],
      "destination_cities": [
        "San Sebastián de los Reyes"
      ],
      "carrier": "",
      "datacenter": "",
      "longitude": -121.895,
      "latitude": 37.3394
    },
    "raw_data": {
      "scan": [],
      "ja3": [],
      "hassh": [],
      "http": {
        "md5": [],
        "cookie_keys": [],
        "request_authorization": [],
        "request_cookies": [],
        "request_header": [],
        "method": [],
        "path": [],
        "request_origin": [],
        "useragent": []
      },
      "source": {
        "bytes": 144
      },
      "tls": {
        "cipher": [],
        "ja4": []
      },
      "ssh": {
        "key": []
      }
    },
    "last_seen_timestamp": "2025-05-25 04:28:29"
  },
  "request_metadata": {
    "restricted_fields": []
  }
}

Multiple IP Lookups

For high-volume enrichments, both the Quick and Full IP lookup functions support sending lists of IPs. Here are some notes on the functionality:

  • Up to 10,000 IPs can be submitted in the POST body of the request
  • IPs not found in GreyNoise will not be included in the standard response, but are available as a list of "ips_not_found"
from greynoise.api import GreyNoise, APIConfig

api_config = APIConfig(api_key="api-key", integration_name="sdk-sample")
session = GreyNoise(api_config)
ips = ['64.39.104.22', '195.72.230.190']

quick_response = session.quick(ips)

print(quick_response)

import requests

context_url = "https://api.greynoise.io/v2/noise/context/"
quick_url = "https://api.greynoise.io/v2/noise/quick/"
riot_url = "https://api.greynoise.io/v2/riot/"
metadata_url = "https://api.greynoise.io/v2/meta/metadata"

headers = {"key": "<api_key>", "Accept": "application/json",
           "User-Agent": "sample-python-script"}

ip_address = '186.33.111.236'
output = []


def build_tag_details(metadata, tags):
    detailed_tags = []
    for tag in tags:
        for detailed_tag in metadata["metadata"]:
            if tag == detailed_tag["name"]:
                detailed_tags.append(detailed_tag)
    return detailed_tags


quick_response = requests.get(quick_url + ip_address, headers=headers)

context_json = {}
riot_json = {}
if quick_response.json()['noise']:
    context_response = requests.get(context_url + ip_address, headers=headers)
    context_json = context_response.json()
    if len(context_json["tags"]) >= 1:
        tags_response = requests.get(metadata_url, headers=headers)
        tags_json = tags_response.json()
        updated_tags = build_tag_details(tags_json, context_json["tags"])
        context_json.pop("tags")
        context_json["tags"] = updated_tags
if quick_response.json()['riot']:
    riot_response = requests.get(riot_url + ip_address, headers=headers)
    riot_json = riot_response.json()

if context_json and riot_json:
    response = context_json.copy()
    response.update(riot_json)
    output.append(response)
elif context_json:
    output = context_json
elif riot_json:
    output = riot_json
else:
    output = quick_response.json()

print(output)

Here is a response Sample from both the Quick and Full APIs. Some fields may be empty in the response based on the level of access of the account being used:

{
  "data": [
    {
      "ip": "64.39.104.22",
      "business_service_intelligence": {
        "found": true,
        "trust_level": "1"
      },
      "internet_scanner_intelligence": {
        "found": true,
        "classification": "benign"
      }
    }
  ],
  "request_metadata": {
    "restricted_fields": [],
    "message": "",
    "ips_not_found": [
      "195.72.230.190"
    ]
  }
}
{
  "data": [
    {
      "ip": "64.39.104.22",
      "business_service_intelligence": {
        "found": true,
        "category": "vulnerability_management",
        "name": "Qualys",
        "description": "Qualys Inc (Qualys) is a provider of cloud-based platform information security and compliance cloud solutions. The company's cloud platform offers private cloud platforms, private cloud platform appliances, public cloud integrations, and cloud agents.",
        "explanation": "Vulnerability management services scan for and track software vulnerabilities. Traffic originating from Qualys may appear to be malicious but it is deliberately trying to identify and remediate vulnerabilities.",
        "last_updated": "2025-08-06T13:10:58Z",
        "reference": "https://www.qualys.com/",
        "trust_level": "1"
      },
      "internet_scanner_intelligence": {
        "first_seen": "2025-05-25",
        "last_seen": "2025-05-25",
        "found": true,
        "tags": [
          {
            "id": "b2cb0f57-9840-4ea7-b403-4899186e259d",
            "slug": "qualys",
            "name": "Qualys",
            "description": "IP addresses with this tag belong to Qualys Inc, a vulnerability management software company.",
            "category": "actor",
            "intention": "benign",
            "references": [
              "https://www.qualys.com/"
            ],
            "cves": [],
            "recommend_block": false,
            "created": "2020-04-07",
            "updated_at": "2025-08-05T22:54:10.464675Z"
          }
        ],
        "actor": "Qualys",
        "spoofable": true,
        "classification": "benign",
        "cves": [],
        "bot": false,
        "vpn": false,
        "vpn_service": "",
        "tor": false,
        "metadata": {
          "asn": "AS27385",
          "source_country": "United States",
          "source_country_code": "US",
          "source_city": "San Jose",
          "domain": "qualys.com",
          "rdns_parent": "",
          "rdns_validated": false,
          "organization": "QUALYS, Inc.",
          "category": "business",
          "rdns": "",
          "os": "",
          "sensor_count": 1,
          "sensor_hits": 2,
          "region": "California",
          "mobile": false,
          "single_destination": true,
          "destination_countries": [
            "Spain"
          ],
          "destination_country_codes": [
            "ES"
          ],
          "destination_asns": [
            "AS174"
          ],
          "destination_cities": [
            "San Sebastián de los Reyes"
          ],
          "carrier": "",
          "datacenter": "",
          "longitude": -121.895,
          "latitude": 37.3394
        },
        "raw_data": {
          "scan": [],
          "ja3": [],
          "hassh": [],
          "http": {
            "md5": [],
            "cookie_keys": [],
            "request_authorization": [],
            "request_cookies": [],
            "request_header": [],
            "method": [],
            "path": [],
            "request_origin": [],
            "useragent": []
          },
          "source": {
            "bytes": 144
          },
          "tls": {
            "cipher": [],
            "ja4": []
          },
          "ssh": {
            "key": []
          }
        },
        "last_seen_timestamp": "2025-05-25 04:28:29"
      }
    }
  ],
  "request_metadata": {
    "restricted_fields": [],
    "message": "",
    "ips_not_found": [
      "195.72.230.190"
    ]
  }
}

Query (GNQL) API Sample

The GreyNoise GNQL API endpoint allows search through the GreyNoise NOISE dataset. The endpoint will take in any query in the GNQL format and provide an output of all the NOISE dataset IPs that match the query.

By default, the endpoint will return 1,000 results per page. The size parameter can be used to up the page limit to 10,000 results per page. When the total number of results exceeds the page size, a scroll token is provided in response to fetch the next set of results.

Here is a sample script for using the GreyNoise SDK to cycle through the GNQL response:

from greynoise.api import GreyNoise, APIConfig

api_config = APIConfig(api_key="<api-key>", integration_name="gnql-sample"
session = GreyNoise(api_config)

query = "last_seen:1d tags:Mirai*"
response = session.query(query, exclude_raw=True, size=10000)
print(f"Total Indicators in Query: {response.get('request_metadata', {}).get('count', 0)}")
data = response["data"]
                       
complete = response.get("request_metadata", {}).get("complete", True)
scroll = response.get("request_metadata", {}).get("scroll", "")
while not complete:
    response = session.query(query, exclude_raw=True, size=10000, scroll=scroll)
    data.extend(response["data"])
    complete = response.get("request_metadata", {}).get("complete", True)   
    scroll = response.get("request_metadata", {}).get("scroll", "")

print(f"Total Indicators in Data Dictionary: {len(data)}")

API Responses

All API Response can be found in the API Reference section.

Updated 7 days ago