GreyNoise Getting Started: First API Call (2026 Guide)

Getting started overview

This guide outlines the essential steps to initiate interaction with the GreyNoise API. It covers account creation, API key retrieval, and executing a foundational API request. GreyNoise assists security teams by categorizing internet-scanning IP addresses, distinguishing between opportunistic attacks, benign services, and targeted threats. Understanding these categories allows for more efficient threat prioritization and noise reduction in security operations. The GreyNoise platform offers various tools beyond the API, including the GreyNoise Visualizer and GreyNoise Analyze, which provide graphical interfaces for exploring threat intelligence data.

Before making your first API call, you will need to:

1. Create a GreyNoise account.
2. Generate or locate your API key.
3. Choose an API endpoint and construct your request.

GreyNoise offers a Community tier that provides free API access with limitations, allowing developers to experiment and build integrations. Paid tiers, such as Professional and Enterprise, offer expanded data access and higher rate limits, suitable for production environments and larger security operations centers (SOCs).

Create an account and get keys

Accessing the GreyNoise API requires an API key for authentication. This key is tied to your GreyNoise account and grants permission to make requests. GreyNoise primarily uses API keys for authentication, a common method for securing access to web services. For more complex authentication scenarios or when integrating with other platforms, understanding broader API security principles, such as OAuth 2.0, can be beneficial, though not directly required for initial GreyNoise API access. The OAuth 2.0 authorization framework provides a secure method for delegated access.

Step 1: Sign up for a GreyNoise account

Navigate to the GreyNoise signup page. You can sign up using an email address or through single sign-on (SSO) options like Google or Microsoft. If you opt for email registration, you will need to verify your email address to activate your account.

Step 2: Locate or generate your API key

Once your account is active, log in to the GreyNoise platform. Your API key is accessible from your account settings or profile page. Typically, it's found under a section labeled "API Keys" or "Integrations." If a key isn't automatically generated, there will be an option to create a new one. Treat your API key as sensitive credentials; do not expose it in client-side code, public repositories, or unsecured environments.

For example, within the GreyNoise interface, you can usually find your API key by navigating to Account > API Keys. Copy this key, as it will be required for every authenticated API request. GreyNoise also offers API key management documentation for detailed instructions on managing your keys, including rotation and revocation.

Your first request

With an API key in hand, you can now make your first request to the GreyNoise API. This example uses the /v2/noise/quick endpoint, which provides a fast lookup for an IP address to determine if it is observed as "noise" by GreyNoise. The API supports various endpoints for different types of queries, including IP reputation, riot information, and bulk lookups. The GreyNoise API reference provides comprehensive details on available endpoints and request parameters.

Using cURL

cURL is a command-line tool for making HTTP requests and is suitable for quick tests. Replace YOUR_API_KEY with your actual GreyNoise API key and 1.1.1.1 with the IP address you wish to query.

curl -X GET "https://api.greynoise.io/v2/noise/quick/1.1.1.1" \
  -H "accept: application/json" \
  -H "key: YOUR_API_KEY"

Expected successful response (JSON format):

{
  "ip": "1.1.1.1",
  "noise": false,
  "riot": true,
  "message": "IP is not GreyNoise, and is in the RIOT list."
}

This response indicates that 1.1.1.1 is not classified as "noise" by GreyNoise and is part of the RIOT (Really Internet Obscure Threats) list, which contains common, benign scanning IP addresses.

Using Python (with requests library)

GreyNoise provides an official Python SDK, but you can also use the popular requests library for direct API calls. First, ensure you have the requests library installed: pip install requests.

import requests

api_key = "YOUR_API_KEY" # Replace with your GreyNoise API key
ip_address = "8.8.8.8" # Example IP address

url = f"https://api.greynoise.io/v2/noise/quick/{ip_address}"
headers = {
    "accept": "application/json",
    "key": api_key
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except Exception as err:
    print(f"Other error occurred: {err}")

Expected successful response (JSON format):

{
  "ip": "8.8.8.8",
  "noise": false,
  "riot": true,
  "message": "IP is not GreyNoise, and is in the RIOT list."
}

This Python example performs the same quick lookup, demonstrating how to handle the API key in headers and process the JSON response. The response.raise_for_status() line is crucial for robust error handling, as it automatically flags non-2xx HTTP responses as exceptions, preventing silent failures.

Common next steps

Once you have successfully made your first API call, consider these next steps to further integrate GreyNoise into your security workflows:

• Explore other endpoints: The GreyNoise API offers various endpoints beyond /v2/noise/quick. For example, /v2/noise/context/{ip} provides more detailed information about an IP address, including its classification, associated tags, and observed activity. Review the full API reference for available endpoints and their capabilities.
• Integrate with security tools: GreyNoise data can enhance existing security information and event management (SIEM) systems, threat intelligence platforms, or security orchestration, automation, and response (SOAR) solutions. Many platforms support custom API integrations for pulling in external data.
• Utilize SDKs: For more complex integrations or application development, consider using the official Python SDK or Go SDK. These SDKs abstract away HTTP request details, simplifying interaction with the API and providing language-specific constructs for data handling.
• Implement webhooks: For real-time notifications, investigate GreyNoise's webhook capabilities if available, which can push updates to your systems when certain conditions are met, reducing the need for constant polling. Twilio's webhook security guide provides useful information on securing webhook implementations, which is a critical consideration for any real-time data integration.
• Monitor API usage: Keep track of your API usage against your plan's rate limits. GreyNoise typically provides dashboards or API endpoints to monitor your consumption, helping you avoid unexpected service interruptions.
• Upgrade your plan: If your usage exceeds the Community tier's limits or you require access to more comprehensive data, consider upgrading to a Professional or Enterprise plan.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

For persistent issues, consult the GreyNoise documentation FAQ or contact GreyNoise support directly for assistance. Providing your request details, API key (if safe to share with support), and the exact error message will help expedite resolution.