Quickstart Guide

Welcome to urlscan.io! This quickstart guide will help you get started with our API, allowing you to make your first API call and begin using the platform programmatically.

Step 1: Sign Up and Get Your API Key

1. Create a user account on urlscan.io via the Sign-Up Page.
2. Log in and go to Settings & API
3. Create a new API key via the New API key button.

Your API key is required to authenticate all API requests.

Step 2: Make Your First API Request

Let's start by making a simple request to the urlscan API to submit a URL for scanning and retrieve the results.

Submit the URL

Use the following curl command to submit a URL for scanning:

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

• url: The full URL you want to scan.
• visibility: The visibility of the scan result.

Response Example

{
  "message": "Submission successful",
  "uuid": "0196d976-07f6-7aae-8a57-aa019145f31c",
  "result": "https://urlscan.io/result/0196d976-07f6-7aae-8a57-aa019145f31c/",
  "api": "https://urlscan.io/api/v1/result/0196d976-07f6-7aae-8a57-aa019145f31c/",
  "visibility": "public",
  "url": "https://example.com"
}

This response confirms that the URL was submitted for scanning and provides the uuid for the scan result. You will have to use the uuid to poll for the result until the scan has finished.

Step 3: Retrieve the result

Scan results will take at least 30 seconds to finish, so you should wait for this long before making your first attempt to retrieve the scan result from urlscan. Even after those initial 30 seconds, the scan might take longer to finish depending on the page and the load of our platform, so you will have to keep polling the result until it becomes available:

curl -H "API-Key: YOUR_API_KEY" https://urlscan.io/api/v1/result/$uuid/

Response Example

Until a scan is finished, this URL will respond with a HTTP/404 status code. If a scan result has been deleted, it will respond with an HTTP/410 error code. This can happen at any time, even right after scan submission!

Once the scan is finished, the Result API URL will respond with HTTP/200 and return a JSON object with a number of properties. The properties are documented in detail in the Result API Reference.

With the UUID you can also retrieve the DOM Snapshot and PNG Screenshot for a particular scan using the following URLs:

curl -H "API-Key: YOUR_API_KEY" https://urlscan.io/screenshots/$uuid.png
curl -H "API-Key: YOUR_API_KEY" https://urlscan.io/dom/$uuid/

If either of these endpoints respond with HTTP/404 after the scan has finished it means that we did not store the DOM snapshot or screenshot.

Congratulations!

You’ve just scanned your first URL and retrieved the results from urlscan.