# 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](https://urlscan.io/user/signup).
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:


```bash
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


```json
{
  "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:


```bash
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:


```bash
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.