API Endpoints
/
Incidents

urlscan.io APIs (1.0.0)

Introduction

API endpoints for urlscan.io and urlscan Pro. Most of these API endpoints require authentication.

The fastest way to start working with our APIs is by using one of the many existing commercial or open-source integrations.

External Resources

Download OpenAPI description
urlscan-openapi.json
urlscan-openapi.yaml
Overview
urlscan Support

support@urlscan.io

Languages
Servers

https://urlscan.io/

Generic

API endpoints related to the platform or the user account.

Operations

Scanning

These APIs allow URLs to be scanned and the results of the scans to be retrieved.

Operations

Search

The Search API allows users to search for historically website scans, hostnames, domains, TLS certificates and incidents.

Operations

Live Scanning

urlscan Pro - Live Scanning allows users to scan websites from different geographical locations and using different device settings.

See additional info about this proprietary feature on urlscan Pro.

Operations

Saved Searches

urlscan Pro - Saved Searches are rules that are executed inline against new incoming scans and hostnames.

Operations

Subscriptions

urlscan Pro - Subscriptions allow notifications for Saved Searches.

Operations

Hostnames

urlscan Pro - Historical information on hostnames and domains

Operations

Brands

urlscan Pro - Information about tracked brands

Operations

Files

urlscan Pro - Downloaded files

Operations

Incidents

urlscan Pro - Incidents track observables, like hostnames and domains, and automatically scan and alert on changes.

Operations

Create Incident

Request

Create an incident with specific options

Security
apikeyAuth
Bodyapplication/json
incidentobjectrequired
Example: {"scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"observable":"foobar.com","visibility":"private","channels":["{{channelId}}"],"scanIntervalMode":"automatic","expireAfter":86400}
incident.​expireAfterinteger

Seconds until the incident will automatically be closed.

Example: 86400
incident.​channelsArray of stringsrequired

Channels subscribed to this incident.

Example: ["{{channelId}}"]
incident.​observablestringrequired

Hostname, domain, IP, or URL to observe

Example: "foobar.com"
incident.​visibilitystringrequired

Scan visibility

Enum"unlisted""private"
Example: "private"
incident.​scanIntervalinteger

Interval (seconds) between triggering full website scans.

Example: 3600
incident.​scanIntervalModestring

If this is set to manual then scanIntervalAfterSuspended and scanIntervalAfterMalicious will not have an effect.

Enum"manual""automatic"
Example: "automatic"
incident.​watchedAttributesArray of strings

Determine which items will be monitored for.

Items Enum"detections""tls""dns""labels""page""meta""ip"
Example: ["detections","tls"]
incident.​userAgentsArray of strings

Browser User-Agents to use during scanning

Example: ["Chrome on Linux","Chrome on macOS"]
incident.​userAgentsPerIntervalinteger

How many userAgents to use per scanInterval

Example: 1
incident.​countriesArray of strings

List of countries to scan from as ISO-3166-1 country codes.

Example: ["de","us"]
incident.​countriesPerIntervalinteger

How many countries to use per scan interval.

Example: 2
incident.​stopDelaySuspendedinteger

When to automatically close the incident after the observable was suspended.

Example: 3600
incident.​stopDelayInactiveinteger

When to automatically close the incident after the observable became inactive.

Example: 86400
incident.​stopDelayMaliciousinteger

When to automatically close the incident after the observable became malicious.

Example: 90000
incident.​scanIntervalAfterSuspendedinteger

How to change the scan interval after the observable was suspended.

Example: 86400
incident.​scanIntervalAfterMaliciousinteger

How to change the scan interval after the observable became malicious.

Example: 86400
incident.​incidentProfilestring

ID of the incident profile to use when creating this incident.

curl -i -X POST \
  https://urlscan.io/api/v1/user/incidents \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "incident": {
      "scanInterval": 3600,
      "watchedAttributes": [
        "detections",
        "tls"
      ],
      "userAgents": [
        "Chrome on Linux",
        "Chrome on macOS"
      ],
      "userAgentsPerInterval": 1,
      "countries": [
        "de",
        "us"
      ],
      "countriesPerInterval": 2,
      "stopDelaySuspended": 3600,
      "stopDelayInactive": 86400,
      "stopDelayMalicious": 90000,
      "scanIntervalAfterSuspended": 86400,
      "scanIntervalAfterMalicious": 86400,
      "observable": "foobar.com",
      "visibility": "private",
      "channels": [
        "{{channelId}}"
      ],
      "scanIntervalMode": "automatic",
      "expireAfter": 86400
    }
  }'

Responses

Incident body

Bodyapplication/json
incidentobject
Example: {"_id":"{{incidentId}}","scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"owner":"own","type":"hostname","observable":"foobar.com","state":"active","visibility":"private","channels":["{{channelId}}"],"sourceType":"manual","sourceId":"{{sourceId}}","stateSize":3717,"stateCount":3,"scanIntervalMode":"automatic","labels":["hasHTTP","hasIP","hasMX","hasNS"],"expireAt":"2025-01-24T11:44:52.563Z","createdAt":"2025-01-21T11:44:52.566Z","scannedAt":"2025-01-21T12:44:52.566Z"}
Response
application/json
{
  "incident": {
    "_id": "{{incidentId}}",
    "scanInterval": 3600,
    "watchedAttributes": [ … ],
    "userAgents": [ … ],
    "userAgentsPerInterval": 1,
    "countries": [ … ],
    "countriesPerInterval": 2,
    "stopDelaySuspended": 3600,
    "stopDelayInactive": 86400,
    "stopDelayMalicious": 90000,
    "scanIntervalAfterSuspended": 86400,
    "scanIntervalAfterMalicious": 86400,
    "owner": "own",
    "type": "hostname",
    "observable": "foobar.com",
    "state": "active",
    "visibility": "private",
    "channels": [ … ],
    "sourceType": "manual",
    "sourceId": "{{sourceId}}",
    "stateSize": 3717,
    "stateCount": 3,
    "scanIntervalMode": "automatic",
    "labels": [ … ],
    "expireAt": "2025-01-24T11:44:52.563Z",
    "createdAt": "2025-01-21T11:44:52.566Z",
    "scannedAt": "2025-01-21T12:44:52.566Z"
  }
}

Get Incident

Request

Get details for a specific incident.

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

curl -i -X GET \
  'https://urlscan.io/api/v1/user/incidents/{incidentId}' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Incident body

Bodyapplication/json
incidentobject
Example: {"_id":"{{incidentId}}","scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"owner":"own","type":"hostname","observable":"foobar.com","state":"active","visibility":"private","channels":["{{channelId}}"],"sourceType":"manual","sourceId":"{{sourceId}}","stateSize":3717,"stateCount":3,"scanIntervalMode":"automatic","labels":["hasHTTP","hasIP","hasMX","hasNS"],"expireAt":"2025-01-24T11:44:52.563Z","createdAt":"2025-01-21T11:44:52.566Z","scannedAt":"2025-01-21T12:44:52.566Z"}
Response
application/json
{
  "incident": {
    "_id": "{{incidentId}}",
    "scanInterval": 3600,
    "watchedAttributes": [ … ],
    "userAgents": [ … ],
    "userAgentsPerInterval": 1,
    "countries": [ … ],
    "countriesPerInterval": 2,
    "stopDelaySuspended": 3600,
    "stopDelayInactive": 86400,
    "stopDelayMalicious": 90000,
    "scanIntervalAfterSuspended": 86400,
    "scanIntervalAfterMalicious": 86400,
    "owner": "own",
    "type": "hostname",
    "observable": "foobar.com",
    "state": "active",
    "visibility": "private",
    "channels": [ … ],
    "sourceType": "manual",
    "sourceId": "{{sourceId}}",
    "stateSize": 3717,
    "stateCount": 3,
    "scanIntervalMode": "automatic",
    "labels": [ … ],
    "expireAt": "2025-01-24T11:44:52.563Z",
    "createdAt": "2025-01-21T11:44:52.566Z",
    "scannedAt": "2025-01-21T12:44:52.566Z"
  }
}

Update Incident options

Request

Update specific runtime options of the incident

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

Bodyapplication/json
incidentobjectrequired
Example: {"scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"observable":"foobar.com","visibility":"private","channels":["{{channelId}}"],"scanIntervalMode":"automatic","expireAfter":86400}
incident.​expireAfterinteger

Seconds until the incident will automatically be closed.

Example: 86400
incident.​channelsArray of stringsrequired

Channels subscribed to this incident.

Example: ["{{channelId}}"]
incident.​observablestringrequired

Hostname, domain, IP, or URL to observe

Example: "foobar.com"
incident.​visibilitystringrequired

Scan visibility

Enum"unlisted""private"
Example: "private"
incident.​scanIntervalinteger

Interval (seconds) between triggering full website scans.

Example: 3600
incident.​scanIntervalModestring

If this is set to manual then scanIntervalAfterSuspended and scanIntervalAfterMalicious will not have an effect.

Enum"manual""automatic"
Example: "automatic"
incident.​watchedAttributesArray of strings

Determine which items will be monitored for.

Items Enum"detections""tls""dns""labels""page""meta""ip"
Example: ["detections","tls"]
incident.​userAgentsArray of strings

Browser User-Agents to use during scanning

Example: ["Chrome on Linux","Chrome on macOS"]
incident.​userAgentsPerIntervalinteger

How many userAgents to use per scanInterval

Example: 1
incident.​countriesArray of strings

List of countries to scan from as ISO-3166-1 country codes.

Example: ["de","us"]
incident.​countriesPerIntervalinteger

How many countries to use per scan interval.

Example: 2
incident.​stopDelaySuspendedinteger

When to automatically close the incident after the observable was suspended.

Example: 3600
incident.​stopDelayInactiveinteger

When to automatically close the incident after the observable became inactive.

Example: 86400
incident.​stopDelayMaliciousinteger

When to automatically close the incident after the observable became malicious.

Example: 90000
incident.​scanIntervalAfterSuspendedinteger

How to change the scan interval after the observable was suspended.

Example: 86400
incident.​scanIntervalAfterMaliciousinteger

How to change the scan interval after the observable became malicious.

Example: 86400
incident.​incidentProfilestring

ID of the incident profile to use when creating this incident.

curl -i -X PUT \
  'https://urlscan.io/api/v1/user/incidents/{incidentId}' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "incident": {
      "scanInterval": 3600,
      "watchedAttributes": [
        "detections",
        "tls"
      ],
      "userAgents": [
        "Chrome on Linux",
        "Chrome on macOS"
      ],
      "userAgentsPerInterval": 1,
      "countries": [
        "de",
        "us"
      ],
      "countriesPerInterval": 2,
      "stopDelaySuspended": 3600,
      "stopDelayInactive": 86400,
      "stopDelayMalicious": 90000,
      "scanIntervalAfterSuspended": 86400,
      "scanIntervalAfterMalicious": 86400,
      "observable": "foobar.com",
      "visibility": "private",
      "channels": [
        "{{channelId}}"
      ],
      "scanIntervalMode": "automatic",
      "expireAfter": 86400
    }
  }'

Responses

Incident body

Bodyapplication/json
incidentobject
Example: {"_id":"{{incidentId}}","scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"owner":"own","type":"hostname","observable":"foobar.com","state":"active","visibility":"private","channels":["{{channelId}}"],"sourceType":"manual","sourceId":"{{sourceId}}","stateSize":3717,"stateCount":3,"scanIntervalMode":"automatic","labels":["hasHTTP","hasIP","hasMX","hasNS"],"expireAt":"2025-01-24T11:44:52.563Z","createdAt":"2025-01-21T11:44:52.566Z","scannedAt":"2025-01-21T12:44:52.566Z"}
Response
application/json
{
  "incident": {
    "_id": "{{incidentId}}",
    "scanInterval": 3600,
    "watchedAttributes": [ … ],
    "userAgents": [ … ],
    "userAgentsPerInterval": 1,
    "countries": [ … ],
    "countriesPerInterval": 2,
    "stopDelaySuspended": 3600,
    "stopDelayInactive": 86400,
    "stopDelayMalicious": 90000,
    "scanIntervalAfterSuspended": 86400,
    "scanIntervalAfterMalicious": 86400,
    "owner": "own",
    "type": "hostname",
    "observable": "foobar.com",
    "state": "active",
    "visibility": "private",
    "channels": [ … ],
    "sourceType": "manual",
    "sourceId": "{{sourceId}}",
    "stateSize": 3717,
    "stateCount": 3,
    "scanIntervalMode": "automatic",
    "labels": [ … ],
    "expireAt": "2025-01-24T11:44:52.563Z",
    "createdAt": "2025-01-21T11:44:52.566Z",
    "scannedAt": "2025-01-21T12:44:52.566Z"
  }
}

Close Incident

Request

Close (stop) the incident

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

Bodyapplication/json
curl -i -X PUT \
  'https://urlscan.io/api/v1/user/incidents/{incidentId}/close' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Restart Incident

Request

Restart a closed incident. Automatically extends the incident expireAt. Starts with new incident states.

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

Bodyapplication/json
curl -i -X PUT \
  'https://urlscan.io/api/v1/user/incidents/{incidentId}/restart' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Copy Incident

Request

Copy an incident without its history.

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

Bodyapplication/json
curl -i -X POST \
  'https://urlscan.io/api/v1/user/incidents/{incidentId}/copy' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Incident body

Bodyapplication/json
incidentobject
Example: {"_id":"{{incidentId}}","scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"owner":"own","type":"hostname","observable":"foobar.com","state":"active","visibility":"private","channels":["{{channelId}}"],"sourceType":"manual","sourceId":"{{sourceId}}","stateSize":3717,"stateCount":3,"scanIntervalMode":"automatic","labels":["hasHTTP","hasIP","hasMX","hasNS"],"expireAt":"2025-01-24T11:44:52.563Z","createdAt":"2025-01-21T11:44:52.566Z","scannedAt":"2025-01-21T12:44:52.566Z"}
Response
application/json
{
  "incident": {
    "_id": "{{incidentId}}",
    "scanInterval": 3600,
    "watchedAttributes": [ … ],
    "userAgents": [ … ],
    "userAgentsPerInterval": 1,
    "countries": [ … ],
    "countriesPerInterval": 2,
    "stopDelaySuspended": 3600,
    "stopDelayInactive": 86400,
    "stopDelayMalicious": 90000,
    "scanIntervalAfterSuspended": 86400,
    "scanIntervalAfterMalicious": 86400,
    "owner": "own",
    "type": "hostname",
    "observable": "foobar.com",
    "state": "active",
    "visibility": "private",
    "channels": [ … ],
    "sourceType": "manual",
    "sourceId": "{{sourceId}}",
    "stateSize": 3717,
    "stateCount": 3,
    "scanIntervalMode": "automatic",
    "labels": [ … ],
    "expireAt": "2025-01-24T11:44:52.563Z",
    "createdAt": "2025-01-21T11:44:52.566Z",
    "scannedAt": "2025-01-21T12:44:52.566Z"
  }
}

Fork Incident

Request

Copy an incident along with its history (incident states).

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

Bodyapplication/json
curl -i -X POST \
  'https://urlscan.io/api/v1/user/incidents/{incidentId}/fork' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Incident body

Bodyapplication/json
incidentobject
Example: {"_id":"{{incidentId}}","scanInterval":3600,"watchedAttributes":["detections","tls"],"userAgents":["Chrome on Linux","Chrome on macOS"],"userAgentsPerInterval":1,"countries":["de","us"],"countriesPerInterval":2,"stopDelaySuspended":3600,"stopDelayInactive":86400,"stopDelayMalicious":90000,"scanIntervalAfterSuspended":86400,"scanIntervalAfterMalicious":86400,"owner":"own","type":"hostname","observable":"foobar.com","state":"active","visibility":"private","channels":["{{channelId}}"],"sourceType":"manual","sourceId":"{{sourceId}}","stateSize":3717,"stateCount":3,"scanIntervalMode":"automatic","labels":["hasHTTP","hasIP","hasMX","hasNS"],"expireAt":"2025-01-24T11:44:52.563Z","createdAt":"2025-01-21T11:44:52.566Z","scannedAt":"2025-01-21T12:44:52.566Z"}
Response
application/json
{
  "incident": {
    "_id": "{{incidentId}}",
    "scanInterval": 3600,
    "watchedAttributes": [ … ],
    "userAgents": [ … ],
    "userAgentsPerInterval": 1,
    "countries": [ … ],
    "countriesPerInterval": 2,
    "stopDelaySuspended": 3600,
    "stopDelayInactive": 86400,
    "stopDelayMalicious": 90000,
    "scanIntervalAfterSuspended": 86400,
    "scanIntervalAfterMalicious": 86400,
    "owner": "own",
    "type": "hostname",
    "observable": "foobar.com",
    "state": "active",
    "visibility": "private",
    "channels": [ … ],
    "sourceType": "manual",
    "sourceId": "{{sourceId}}",
    "stateSize": 3717,
    "stateCount": 3,
    "scanIntervalMode": "automatic",
    "labels": [ … ],
    "expireAt": "2025-01-24T11:44:52.563Z",
    "createdAt": "2025-01-21T11:44:52.566Z",
    "scannedAt": "2025-01-21T12:44:52.566Z"
  }
}

Get Watchable Attributes

Request

Get the list of attributes which can be supplied to the watchedAttributes property of the incident.

Security
apikeyAuth
curl -i -X GET \
  https://urlscan.io/api/v1/user/watchableAttributes \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Get Incident States

Request

Retrieve individual incident states of an incident.

Security
apikeyAuth
Path
incidentIdstringrequired

ID of incident

curl -i -X GET \
  'https://urlscan.io/api/v1/user/incidentstates/{incidentId}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
incidentstatesArray of objects
Response
application/json
{
  "incidentstates": [
    { … }
  ]
}

Channels

Operations