Shodan Getting Started: API Access & First Query (2026)

Getting started overview

This guide provides a focused walkthrough for initiating interaction with the Shodan API. It covers the essential steps from account creation and API key retrieval to executing a foundational API request. Shodan functions as a search engine for internet-connected devices, enabling users to programmatically discover and analyze device data such as open ports, banners, and vulnerabilities Shodan developer documentation. The API facilitates integration into custom applications for cybersecurity research, asset management, and threat intelligence.

Before proceeding, ensure you have an active Shodan account. The API offers various endpoints to query Shodan's database, including device search, host information retrieval, and network scanning functionalities. Authentication for all API requests is handled via a unique API key.

Quick Reference Steps

Create an account and get keys

Accessing the Shodan API requires an account and an associated API key. The API key serves as the primary authentication method for all programmatic interactions. Shodan offers a free tier with limited query and scan credits, which is sufficient for initial testing and development.

Account Creation

1. Navigate to the Shodan registration page.
2. Provide a valid email address, choose a username, and set a password.
3. Complete any required CAPTCHA verification.
4. Verify your email address by following the instructions sent to your inbox.

API Key Retrieval

Once your account is active, your API key will be available in your account profile:

1. Log in to your Shodan account on the Shodan homepage.
2. Access your profile page. This is typically found under your username or an 'Account' link in the navigation. The direct link is your Shodan account profile.
3. Locate the section labeled 'API Key'. Your unique API key, a hexadecimal string, will be displayed here.
4. Copy this key securely. It should be treated like a password, as it grants access to your Shodan account's API credits and data.

It is recommended to store your API key in environment variables or a secure configuration management system rather than hardcoding it directly into your application code.

Your first request

This section demonstrates how to make a basic API request to Shodan using both curl, a common command-line tool for making HTTP requests, and the official Shodan Python library. Replace YOUR_API_KEY with the actual API key obtained from your Shodan profile.

Using curl

The simplest way to test your API key is to use curl to query the /api-info endpoint, which provides information about your API plan and credit limits without consuming search credits.

curl "https://api.shodan.io/api-info?key=YOUR_API_KEY"

A successful response will return a JSON object similar to this:

{
  "query_credits": 100,
  "scan_credits": 100,
  "usage_limits": {
    "query_credits": 100,
    "scan_credits": 100
  },
  "plan": "free",
  "telnet": false,
  "unlocked_left": 0,
  "unlocked_right": 0,
  "monitored_ips": null,
  "api_key": "YOUR_API_KEY"
}

To perform a search for devices, you can use the /shodan/host/search endpoint. For example, to search for webcams:

curl "https://api.shodan.io/shodan/host/search?key=YOUR_API_KEY&query=webcam"

Using the Python SDK

Shodan provides official SDKs for several programming languages to simplify API interactions. The Python SDK is a common choice. First, install the SDK:

pip install shodan

Next, use the following Python code to perform the same api-info and host search queries:

import shodan
import os

# It's recommended to store your API key as an environment variable
# For testing, you can replace os.environ.get with your actual key string
SHODAN_API_KEY = os.environ.get("SHODAN_API_KEY", "YOUR_API_KEY")

api = shodan.Shodan(SHODAN_API_KEY)

try:
    # Get API key info
    info = api.info()
    print("API Info:", info)

    # Search for devices
    results = api.search('webcam')
    print('Search Results found:', results['total'])
    for result in results['matches']:
        print('  IP: %s' % result['ip_str'])
        print('  Organization: %s' % result.get('org', 'N/A'))
        print('  Port: %s' % result['port'])
        print('  Data: %s' % result['data'].split('\n')[0])
        print('')

except shodan.APIError as e:
    print('Error: %s' % e)

This script initializes the Shodan API client with your key and then executes two common API calls, printing the results or any encountered errors. For detailed information on the Python SDK, refer to the Shodan Python library documentation.

Common next steps

After successfully making your first API calls, consider these next steps to further integrate Shodan into your workflows:

• Explore Query Filters: Shodan's search query syntax supports numerous filters (e.g., country, port, org, product, has_screenshot) for granular data retrieval. Experiment with different filters to refine your searches. The Shodan Query Guide provides comprehensive details.
• Understand API Endpoints: Familiarize yourself with other available API endpoints beyond basic search, such as those for host lookups, network alerts, and bulk data downloads. The full Shodan API reference details all functionalities.
• Integrate with Security Tools: Shodan data can augment existing security information and event management (SIEM) systems, vulnerability scanners, or threat intelligence platforms. For example, integrating Shodan data into a system like Splunk or Elastic Security can provide external context about internet-facing assets Elastic Security SIEM explanation.
• Monitor Assets with Shodan Monitor: If you have specific IP ranges or domains to track, Shodan Monitor can alert you to changes in their exposed services or newly discovered vulnerabilities.
• Review Rate Limits and Pricing: Understand the Shodan pricing structure and API rate limits relevant to your account plan to ensure uninterrupted service and plan for scaling.

Troubleshooting the first call

If your initial Shodan API call fails, consider the following common issues and solutions:

• Incorrect API Key: Double-check that the API key you are using exactly matches the one displayed on your Shodan profile page. API keys are case-sensitive.
• Network Connectivity: Ensure your system has active internet access and can reach api.shodan.io. Test with a simple ping or web browser access to a known site.
• Firewall/Proxy Issues: Corporate firewalls or proxies might block outbound connections to Shodan's API servers. Consult your network administrator if you suspect this is the case.
• Insufficient Credits: While the /api-info endpoint does not consume credits, search queries do. If you are on the free tier, you have limited Shodan query credits. Check your remaining credits via the /api-info endpoint.
• API Endpoint Typos: Verify that the API endpoint URL is correct (e.g., https://api.shodan.io/api-info, not https://api.shodan.io/info). Refer to the Shodan API Reference for exact endpoint paths.
• SDK Specific Errors: If using an SDK, ensure it's installed correctly and that your code handles potential exceptions (e.g., shodan.APIError in Python) as demonstrated in the example. Review the SDK's documentation for specific error handling guidance.
• Rate Limiting: If you are making many requests in a short period, you might hit Shodan's rate limits. The API will return an HTTP 429 status code (Too Many Requests). Implement exponential backoff or ensure your request frequency aligns with your plan's limits.