URLScan.io Getting Started: First Scan & API Keys (2026)

Getting started overview

This guide provides a focused walkthrough for initiating your interaction with URLScan.io. It covers the essential steps from creating an account and acquiring API credentials to executing your first scan request. The primary goal is to enable new users to quickly submit a URL for analysis and retrieve its report, establishing a foundational understanding of the platform's API functionality.

URLScan.io functions by navigating to a user-submitted URL and recording information such as the IP addresses visited, domains contacted, and a screenshot of the page content. This data can then be used for security research, identifying malicious websites, or gathering threat intelligence. For detailed API specifications and broader capabilities, consult the URLScan.io API documentation.

Quick Reference Table

Create an account and get keys

To begin using URLScan.io, a user account is required to generate and manage API keys. The platform offers a free tier that supports 50 public scans per day for non-commercial use, which is sufficient for initial testing and exploration of its capabilities. Paid tiers, starting at $49/month, offer increased scan limits and private scanning features.

1. Visit the Signup Page: Navigate to the URLScan.io login/signup page.
2. Register for an Account: Provide the necessary information to create your account. This typically includes an email address and a password.
3. Verify Email (if required): Follow any instructions to verify your email address.
4. Locate Your API Key: Once logged in, go to your URLScan.io user profile page. Your API key will be displayed there. Copy this key as it is essential for authenticating your API requests. For security best practices, treat this key like a password and avoid hardcoding it directly into your application's source code. Consider using environment variables or a secure configuration management system.

The API key authenticates your requests, associating them with your account and enforcing your daily scan limits. Without a valid API key, most API endpoints will return an authentication error.

Your first request

After acquiring your API key, you can proceed to submit your first URL for scanning. This section demonstrates how to initiate a scan using both cURL and the official Python SDK, and then how to retrieve the associated scan report.

Submitting a Scan Request

When submitting a scan, you generally send a POST request to the /api/v1/scan/ endpoint with the target URL. The API will respond with a UUID (Universally Unique Identifier) for the scan, which you will use to retrieve the results once the scan is complete.

Using cURL

For quick tests or scripting in environments without dedicated SDKs, cURL is a direct method to interact with the API.

curl -X POST 'https://urlscan.io/api/v1/scan/' \
     -H 'Content-Type: application/json' \
     -H 'API-Key: YOUR_API_KEY' \
     --data '{"url": "https://example.com", "visibility": "public"}'
    

Replace YOUR_API_KEY with your actual API key and https://example.com with the URL you wish to scan. The "visibility": "public" parameter indicates that the scan results will be publicly viewable on URLScan.io. Remove this parameter or set it to "private" for private scans, which may require a paid subscription.

A successful response will look similar to this, providing the uuid:

{
  "message": "Submission successful",
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "result": "https://urlscan.io/api/v1/result/a1b2c3d4-e5f6-7890-1234-567890abcdef/"
}
    

Using Python SDK

The Python SDK simplifies interaction with the URLScan.io API by abstracting HTTP requests and handling JSON parsing. First, install the SDK:

pip install urlscan-py
    

Then, submit a scan using Python:

import os
from urlscan import Urlscan

api_key = os.environ.get("URLSCAN_API_KEY") # Recommended: use environment variables
if not api_key:
    print("Error: URLSCAN_API_KEY environment variable not set.")
    exit(1)

scanner = Urlscan(api_key)
target_url = "https://www.example.org/"

try:
    scan_submission = scanner.scan(url=target_url, public=True) # Set public=False for private scans
    print(f"Scan submitted successfully. UUID: {scan_submission['uuid']}")
    print(f"Report URL: {scan_submission['result']}")
except Exception as e:
    print(f"Error submitting scan: {e}")
    
# The 'scan_submission' dictionary will contain the 'uuid' key.
# You can store this UUID to retrieve results later.
    

Using environment variables for API keys, as shown in the Python example, is a recommended security practice for API keys to prevent their exposure in source code or version control systems.

Retrieving Scan Results

After submitting a scan, the system processes the URL, which can take some time. You can poll the results endpoint using the uuid obtained from the submission response. When the scan is complete, the response will contain the full analysis report.

Using cURL

curl -X GET 'https://urlscan.io/api/v1/result/YOUR_SCAN_UUID/' \
     -H 'API-Key: YOUR_API_KEY'
    

Replace YOUR_SCAN_UUID with the UUID received from your scan submission and YOUR_API_KEY with your API key. The report can be quite extensive, containing details like screenshots, DOM content, network requests, and identified indicators.

Using Python SDK

# Assuming 'scan_submission' from the previous step which contains 'uuid'
scan_uuid = scan_submission['uuid'] # Replace with your actual UUID if running separately

# Polling for results (simplified example - a real application would use proper retry logic)
import time

for _ in range(10): # Try up to 10 times
    try:
        scan_result = scanner.result(scan_uuid)
        if scan_result['task']['time'] is not None: # Check if scan is complete
            print("Scan completed. Full report:")
            # You can access specific parts of the report, e.g., screenshot URL
            if 'screenshot' in scan_result['task']:
                print(f"Screenshot URL: {scan_result['task']['screenshot']}")
            # print(json.dumps(scan_result, indent=2)) # Uncomment to print full JSON
            break
    except Exception as e:
        print(f"Waiting for scan results... {e}")
    time.sleep(10) # Wait 10 seconds before retrying
else:
    print("Scan did not complete within the given time.")
    

The Python SDK's result() method simplifies fetching the report. Real-world applications often implement a more robust polling mechanism with exponential backoff to handle varying scan times and API rate limits effectively, as detailed in Cloudflare's API retry strategy guide.

Common next steps

After successfully performing your first URL scan and retrieving its results, consider these common next steps to further integrate and utilize URLScan.io's features:

• Explore Report Details: Dive into the comprehensive scan report. Understand the different sections, such as data (network requests, DOM), task (scan parameters), list (extracted indicators), and verdicts (potential threats). This will help you interpret the security posture of scanned URLs.
• Automate Scanning: Integrate URLScan.io into your existing security workflows. Use webhooks to receive notifications when scans complete, rather than constant polling. The API supports a webhook parameter in the scan submission, allowing you to specify a callback URL.
• Error Handling: Implement robust error handling in your code to gracefully manage API rate limits, invalid submissions, and other potential issues. Consult the URLScan.io API error codes documentation for a list of possible responses.
• Private Scans: If your use case involves sensitive URLs or internal resources, consider upgrading to a paid plan to enable private scanning. This ensures that your scan targets and results are not publicly accessible on the URLScan.io website.
• Bulk Submissions: For analyses requiring many URLs, explore strategies for bulk submission, potentially by queueing requests and managing API limits.
• Community and Research: Engage with the security community and threat intelligence researchers who use URLScan.io. Understanding common patterns and indicators can enhance your analytical capabilities.

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here's a guide to common problems and their solutions:

• 401 Unauthorized / Invalid API Key:
  • Check API Key: Ensure your API key is correctly copied from your URLScan.io user profile and included in the API-Key header of your request. Keys are case-sensitive.
  • Environment Variable: If using environment variables, verify that URLSCAN_API_KEY is correctly set in your environment before running your script.
• 400 Bad Request / Invalid URL or Parameters:
  • URL Format: Double-check that the url parameter in your request body is a valid and properly encoded URL (e.g., https://www.example.com).
  • JSON Syntax: Ensure your JSON payload is correctly formatted, especially when using cURL. Missing commas, unclosed quotes, or incorrect braces can lead to parsing errors.
  • Required Fields: Verify that all mandatory parameters, such as url, are present in your submission.
• 429 Too Many Requests / Rate Limit Exceeded:
  • Free Tier Limits: Remember that the free tier has a limit of 50 public scans per day. If you exceed this, you'll receive a rate limit error.
  • Wait and Retry: Implement a delay before retrying the request. For automated scripts, consider implementing exponential backoff.
  • Upgrade Plan: If you consistently hit rate limits, consider upgrading your URLScan.io pricing plan for higher limits.
• Scan Not Completing / No Results:
  • Polling Delay: Scans can take time to complete depending on the URL's complexity and server load. Increase your polling interval or retry count.
  • UUID Mismatch: Ensure you are using the exact uuid returned from the scan submission request to fetch the results.
  • Network Issues: Check your internet connectivity and ensure there are no firewalls or network restrictions blocking access to urlscan.io.
• Generic Errors: If you receive an unexpected error and the above steps don't help, consult the official URLScan.io API documentation for specific error codes and their meanings.