---
canonical_url: "https://docs.composio.dev/toolkits/urlscanio"
markdown_url: "https://docs.composio.dev/toolkits/urlscanio.md"
product: "platform"
version: null
last_updated: null
---

# urlscan.io

Submit and retrieve website scans, search urlscan.io data, and manage urlscan Pro resources for threat intelligence and security investigations.

- **Category:** security & identity tools
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 51
- **Triggers:** 0
- **Slug:** `URLSCANIO`
- **Version:** 00000000_00

## Tools

### Close Incident

**Slug:** `URLSCANIO_CLOSE_INCIDENT`

Stop ongoing scans for an active urlscan Pro incident and transition it to the closed state. Closing does not delete the incident or its history, and the incident can later be restarted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `incident_id` | string | Yes | Unique _id of the active incident to stop and close. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Copy Incident

**Slug:** `URLSCANIO_COPY_INCIDENT`

Create a separate urlscan Pro incident from an existing incident's configuration. This create operation can consume incident capacity and does not copy the source incident's stored state history; use the distinct fork operation when history must be preserved. The provider does not document whether the copied incident immediately activates ongoing scans or alerts.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `incident_id` | string | Yes | Unique _id of the source incident whose configuration is copied. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Notification Channel

**Slug:** `URLSCANIO_CREATE_CHANNEL`

Create a Pro notification channel. This operation configures external effects: active webhook channels send requests to the supplied secret URL, and active email channels send messages to the supplied recipients. Confirm the destination and activation settings before calling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable channel name. |
| `type` | string ("webhook" | "email") | Yes | Channel delivery type. Select webhook or email. |
| `utc_time` | string | No | Scheduled UTC delivery time in 24-hour HH:MM format. |
| `frequency` | string ("live" | "hourly" | "daily") | No | Notification delivery frequency. |
| `is_active` | boolean | No | Whether the channel is active. An active channel can send external webhook or email notifications. |
| `week_days` | array | No | Delivery weekdays. |
| `is_default` | boolean | No | Whether this is the account's default notification channel. |
| `ignore_time` | boolean | No | Whether to ignore scheduled delivery timing. |
| `permissions` | array | No | Optional team sharing permissions for the channel. |
| `webhook_url` | string | No | Secret HTTP(S) destination for a webhook channel. It may contain an embedded access token and will receive external notifications. |
| `email_addresses` | array | No | External recipients for an email channel. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Incident

**Slug:** `URLSCANIO_CREATE_INCIDENT`

Create a Pro incident that persistently monitors an observable. This high-impact operation starts ongoing external scans and can send alerts through every supplied notification channel; confirm the observable, visibility, channels, cadence, and expiration settings before calling. The operation is contract-only because the connected build account lacks the urlscan Pro Incidents entitlement.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `channels` | array | Yes | Notification channel IDs that receive alerts from this incident. Calling the tool can cause ongoing external email or webhook delivery. |
| `countries` | array | No | Scanner countries used for recurring incident scans. |
| `extra_path` | string | No | Optional path appended to hostname-type incident scans. |
| `observable` | string | Yes | URL, hostname, or other provider-supported observable to monitor with ongoing scans. Accepted forms are not enumerated by the operation contract. |
| `visibility` | string ("unlisted" | "private") | Yes | Visibility assigned to scans created by this incident. |
| `user_agents` | array | No | User agents used for recurring incident scans. |
| `scan_interval` | integer | No | Interval between ongoing scans; the operation contract does not specify the unit. |
| `runtime_options` | object | No | Optional provider runtime controls for scan rotation, stop delays, post-state intervals, incident profile, and expiration. |
| `scan_interval_mode` | string ("manual" | "automatic") | No | Whether the scan interval is controlled manually or automatically. |
| `watched_attributes` | array | No | Observable changes that create incident states and may trigger alerts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Run Blocking Live Scan

**Slug:** `URLSCANIO_CREATE_LIVE_SCAN_BLOCKING`

Run a temporary Live Scan synchronously and return only after the provider finishes the scan. This requires the separate Live Scanning product.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task` | object | Yes | Required Live Scan task settings sent under the provider's task object. |
| `scanner` | object | No | Optional execution settings sent under the provider's scanner object. |
| `scanner_id` | string | Yes | Scanner identifier returned by LIST_LIVE_SCANNERS. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Live Scan Task

**Slug:** `URLSCANIO_CREATE_LIVE_SCAN_TASK`

Start a non-blocking temporary Live Scan on a selected scanner and return its UUID immediately without waiting for completion. This external scan side effect requires the separate urlscan.io Live Scanning entitlement; a generic Pro plan may not include it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | URL to scan asynchronously. |
| `tags` | array | No | Up to 10 user-defined tags, each no longer than 30 characters. |
| `scanner` | object | No | Optional timing, request-header, and feature settings for the live scanner. |
| `scanner_id` | string | Yes | Live scanner identifier returned by LIST_LIVE_SCANNERS. |
| `visibility` | string ("public" | "unlisted" | "private") | No | Visibility to assign to the temporary Live Scan. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Saved Search

**Slug:** `URLSCANIO_CREATE_SAVED_SEARCH`

Create a reusable scans or hostnames search definition. This operation creates a persistent saved search and requires urlscan Pro; the hostnames datasource may require an additional product entitlement.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tlp` | string ("red" | "amber+strict" | "amber" | "green" | "clear") | No | Optional Traffic Light Protocol marking for other urlscan Pro users. |
| `name` | string | Yes | Human-readable name for the saved search. |
| `query` | string | Yes | urlscan.io Search API query-string expression. |
| `user_tags` | array | No | Optional tags applied to matching items. Prefix tags with pro., public., private., or team. to select their visibility scope. |
| `datasource` | string ("hostnames" | "scans") | Yes | Datasource queried by this saved search. Hostnames requires its Pro product. |
| `description` | string | No | Optional short description of the saved search. |
| `permissions` | array | No | Optional team or public sharing permissions for the saved search. |
| `long_description` | string | No | Optional detailed description of the saved search. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Alert Subscription

**Slug:** `URLSCANIO_CREATE_SUBSCRIPTION`

Create a persistent scheduled or live alert subscription for saved searches. This Pro-only operation has external notification side effects: an active subscription can send email, invoke configured channels or webhooks, and create incidents. Confirm all recipients and channel or incident settings before calling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable subscription name. |
| `frequency` | string ("live" | "hourly" | "daily") | Yes | How often the subscription evaluates and delivers matching results. |
| `is_active` | boolean | Yes | Whether delivery is active. When true, creation may cause external email, channel, webhook, or incident notifications. |
| `week_days` | array | No | Optional provider weekday selection. |
| `search_ids` | array | Yes | Saved-search IDs monitored by the subscription. |
| `channel_ids` | array | No | Notification channel IDs to invoke externally when matching results are delivered. |
| `description` | string | No | Optional subscription description. |
| `ignore_time` | boolean | Yes | Whether the subscription ignores provider timing constraints. |
| `permissions` | array | No | Optional subscription sharing permissions. |
| `email_addresses` | array | Yes | External email recipients for subscription notifications. The provider requires this field even when notification channels are configured. |
| `incident_options` | object | No | Optional incident notification settings. These fields can cause external incident creation when the active subscription matches. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Scan Result

**Slug:** `URLSCANIO_DELETE_RESULT`

Permanently delete a scan owned by the connected user or team. This destructive operation cannot be reversed and requires urlscan Pro.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | Owned scan UUID to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Saved Search

**Slug:** `URLSCANIO_DELETE_SAVED_SEARCH`

Permanently delete a saved search by ID. This destructive operation cannot be undone and requires urlscan Pro saved-search access plus ownership or team write permission. Use it only for a saved search created or explicitly selected by the current workflow.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search_id` | string | Yes | Saved-search ID to permanently delete. Only delete a saved search created or explicitly selected by the current workflow. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Alert Subscription

**Slug:** `URLSCANIO_DELETE_SUBSCRIPTION`

Permanently delete an alert subscription by ID. This destructive operation cannot be undone and requires urlscan Pro subscriptions access plus ownership or team write permission. Use it only for a subscription created or explicitly selected by the current workflow.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Alert subscription ID to permanently delete. Only delete a subscription created or explicitly selected by the current workflow. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Captured File

**Slug:** `URLSCANIO_DOWNLOAD_FILE`

Retrieve a captured binary file by its SHA-256 hash as a password-encrypted ZIP archive. This operation requires urlscan Pro access.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filename` | string | No | Filename for the returned ZIP archive. Defaults to <file_hash>.zip. |
| `password` | string | No | Password used to encrypt the returned ZIP archive. Defaults to urlscan!. |
| `file_hash` | string | Yes | SHA-256 hash of the captured binary file to download. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fork Incident

**Slug:** `URLSCANIO_FORK_INCIDENT`

Create a new Pro incident by copying an existing incident's configuration and complete stored state history. This creates a separate persistent incident; history volume and whether monitoring starts immediately are not documented.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `incident_id` | string | Yes | Source incident _id whose configuration and complete stored state history are copied into a new incident. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account Capabilities

**Slug:** `URLSCANIO_GET_ACCOUNT_CAPABILITIES`

Get non-sensitive plan, product, feature, visibility, submission, and limit information for the connected urlscan.io API key.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Brand Summary

**Slug:** `URLSCANIO_GET_BRAND_SUMMARY`

Return detectable brands with detected-page totals and latest hits. This operation requires urlscan Pro access and uses the official contract only; the provider does not document its response fields.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Notification Channel

**Slug:** `URLSCANIO_GET_CHANNEL`

Get one urlscan Pro notification channel by ID while preserving provider-specific metadata and removing webhook destinations or credentials.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `channel_id` | string | Yes | Unique _id of the notification channel to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Data Dump Download Link

**Slug:** `URLSCANIO_GET_DATA_DUMP_LINK`

Generate a temporary download URL for a path returned by LIST_DATA_DUMPS. Data Dumps require an Enterprise or Ultimate urlscan.io plan.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Data-dump path returned by LIST_DATA_DUMPS. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Scan DOM

**Slug:** `URLSCANIO_GET_DOM`

Return the plain-text DOM snapshot captured for a completed scan.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | Completed scan UUID from SUBMIT_SCAN or SEARCH_SCANS. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Hostname History

**Slug:** `URLSCANIO_GET_HOSTNAME_HISTORY`

Return one page of historical Pro Hostnames observations for a hostname.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Observations to return in this page (10-10000). |
| `hostname` | string | Yes | Hostname to inspect, without a URL path. |
| `next_cursor` | string | No | Opaque pageState returned by a previous GET_HOSTNAME_HISTORY call. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Incident

**Slug:** `URLSCANIO_GET_INCIDENT`

Get one incident's configuration, source, runtime state, and timestamps.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `incident_id` | string | Yes | Unique _id of the incident to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Incident States

**Slug:** `URLSCANIO_GET_INCIDENT_STATES`

Retrieve the stored state history for an incident.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `incident_id` | string | Yes | Incident _id whose stored state history should be retrieved. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Live Scan Resource

**Slug:** `URLSCANIO_GET_LIVE_SCAN_RESOURCE`

Retrieve one temporary result, DOM, screenshot, captured response, or download from the separate urlscan.io Live Scanning product. JSON and text are returned inline; binary content is offloaded as a downloadable file.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scanner_id` | string | Yes | Live scanner identifier from LIST_LIVE_SCANNERS. Live Scanning is a separate urlscan.io product. |
| `resource_id` | string | Yes | Scan UUID for result, screenshot, or dom; SHA-256 resource hash for response or download. Temporary Live Scan resources typically expire about 60 minutes after creation. |
| `resource_type` | string ("result" | "screenshot" | "dom" | "response" | "download") | Yes | Resource kind: result returns JSON, dom returns text, screenshot and download return files, and response follows its captured media type. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Deprecated Phishing Feed

**Slug:** `URLSCANIO_GET_PHISHFEED`

Retrieve the deprecated urlscan Pro phishing feed in JSON, CSV, or TSV. Prefer SEARCH_SCANS for new workflows, as recommended by urlscan.io.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of feed records to return. urlscan.io does not document bounds for this deprecated endpoint. |
| `query` | string | No | Optional urlscan.io query-string filter for detected phishing pages. |
| `format` | string ("csv" | "tsv" | "json") | No | Response representation: json returns structured search results, while csv and tsv return delimited text. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get API Quotas

**Slug:** `URLSCANIO_GET_QUOTAS`

Get current products, features, query capabilities, and per-action minute, hour, and day quota usage.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Captured Response Content

**Slug:** `URLSCANIO_GET_RESPONSE_CONTENT`

Return textual content captured in a scan response, addressed by its SHA-256 hash.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_hash` | string | Yes | SHA-256 response hash from GET_RESULT data.requests. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Scan Result

**Slug:** `URLSCANIO_GET_RESULT`

Retrieve the complete metadata and captured request data for a completed scan UUID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | Scan UUID from SUBMIT_SCAN or SEARCH_SCANS. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Saved Search Results

**Slug:** `URLSCANIO_GET_SAVED_SEARCH_RESULTS`

Run a urlscan Pro saved search and return its current Search API results. The provider redirect is followed automatically; this operation does not expose pagination controls.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search_id` | string | Yes | Unique ID of the saved search to run. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Scan Screenshot

**Slug:** `URLSCANIO_GET_SCREENSHOT`

Retrieve a completed urlscan.io scan screenshot as a downloadable PNG file reference.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | Completed scan UUID from Submit Scan or Search Scans. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Similar Scan Results

**Slug:** `URLSCANIO_GET_SIMILAR_RESULTS`

Find one page of scan results structurally similar to a specified scan. Requires urlscan Pro access.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Maximum results in this page. urlscan.io does not document an operation-specific upper bound for this Pro endpoint. |
| `query` | string | No | Optional urlscan.io query-string expression used to filter similar results. |
| `scan_id` | string | Yes | Reference scan UUID whose structural similarity is evaluated. |
| `next_cursor` | string | No | Opaque continuation returned by a previous GET_SIMILAR_RESULTS call. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Subscription Results

**Slug:** `URLSCANIO_GET_SUBSCRIPTION_RESULTS`

Resolve a urlscan Pro alert subscription and datasource to its current Search API results. The provider redirect is followed automatically; this operation does not expose pagination controls.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `datasource` | string | Yes | Datasource configured for the subscription. The provider does not publish an exhaustive list of accepted values for this operation. |
| `subscription_id` | string | Yes | Unique _id of the alert subscription to resolve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Available Brands

**Slug:** `URLSCANIO_LIST_AVAILABLE_BRANDS`

List brand identifiers and metadata tracked by urlscan.io brand and phishing detection. Requires urlscan Pro brand/phishing access; the exact product and minimum plan are not documented.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Available Scan Countries

**Slug:** `URLSCANIO_LIST_AVAILABLE_COUNTRIES`

List scanner country codes currently accepted by the Scan API.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Notification Channels

**Slug:** `URLSCANIO_LIST_CHANNELS`

List email and webhook notification channels for the current user without returning webhook URLs or embedded credentials. This operation requires urlscan Pro channels access.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Data Dumps

**Slug:** `URLSCANIO_LIST_DATA_DUMPS`

List available urlscan.io data-dump files for a time window, file type, and date. Requires an Enterprise or Ultimate plan; availability can vary by window and file type.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | string | Yes | Calendar date in YYYYMMDD format. |
| `file_type` | string ("api" | "search" | "screenshot" | "dom") | Yes | Dump content family: api, search, screenshot, or dom. |
| `time_window` | string ("days" | "hours" | "minutes") | Yes | Dump aggregation window: days, hours, or minutes. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Live Scanners

**Slug:** `URLSCANIO_LIST_LIVE_SCANNERS`

List Live Scanning nodes available to the connected account and their current metadata. This requires the separate urlscan.io Live Scanning product; a generic urlscan Pro plan may not include it.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Saved Searches

**Slug:** `URLSCANIO_LIST_SAVED_SEARCHES`

List saved searches owned by or shared with the current user. This operation requires urlscan Pro saved-search access.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Alert Subscriptions

**Slug:** `URLSCANIO_LIST_SUBSCRIPTIONS`

List alert subscriptions configured for the current user. This operation requires urlscan Pro subscriptions access.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Scan User Agents

**Slug:** `URLSCANIO_LIST_USER_AGENTS`

List grouped browser user-agent strings available for scan submission.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Watchable Incident Attributes

**Slug:** `URLSCANIO_LIST_WATCHABLE_ATTRIBUTES`

List attribute values accepted when configuring incident change monitoring. Requires urlscan Pro Incidents capability; the exact minimum plan or product is not documented.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Lookup Malicious Observable

**Slug:** `URLSCANIO_LOOKUP_MALICIOUS_OBSERVABLE`

Look up malicious-scan occurrence counts and first/last seen timestamps for an IP, hostname, domain, or exact URL. Requires urlscan Pro malicious-observable access.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("ip" | "hostname" | "domain" | "url") | Yes | Observable kind: IP address, exact hostname, apex domain, or exact URL. |
| `value` | string | Yes | Exact observable value. Provide URLs unencoded; the complete value is safely URL-encoded as one path segment. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Purge Live Scan Result

**Slug:** `URLSCANIO_PURGE_LIVE_SCAN_RESULT`

Permanently delete a temporary result from the separate urlscan.io Live Scanning product before its normal expiration. This destructive operation cannot be undone; only use it to clean up a temporary result created by the current workflow.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | UUID of the temporary Live Scan result to permanently purge before its normal expiration. Only purge a result created for the current workflow. |
| `scanner_id` | string | Yes | Live Scanning node identifier returned by LIST_LIVE_SCANNERS. Live Scanning is a separate urlscan.io product. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Reset Scan Visibility

**Slug:** `URLSCANIO_RESET_RESULT_VISIBILITY`

Remove an owned scan's visibility override and restore the visibility originally assigned at submission. This resets an override; it does not delete the scan. Requires urlscan Pro.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | Owned scan UUID whose visibility override should be removed. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Restart Incident

**Slug:** `URLSCANIO_RESTART_INCIDENT`

Restart a closed urlscan Pro incident and extend its expiry. This resumes ongoing external monitoring, begins recording new incident states, and can resume alerts through the incident's configured notification channels; confirm the incident should become active again before calling. This operation is contract-only because the connected build account lacks Pro Incidents access.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `incident_id` | string | Yes | Unique _id of the closed incident to restart. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Scans

**Slug:** `URLSCANIO_SEARCH_SCANS`

Search urlscan.io data with Elasticsearch Query String syntax and return one controllable page of results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Results in this page (1-10000). The connected account may enforce a lower maximum; 1000 was verified for a free account. |
| `query` | string | No | Provider query-string expression. Results follow urlscan.io semantics and may not strictly match intuitive filtering. |
| `collapse` | string | No | Optional provider field used to collapse duplicate results. |
| `datasource` | string ("scans" | "hostnames" | "incidents" | "notifications" | "certificates") | No | Datasource to query. Only scans is available without the corresponding urlscan Pro entitlement. |
| `next_cursor` | string | No | Opaque continuation returned by a previous SEARCH_SCANS call. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Store Live Scan Result

**Slug:** `URLSCANIO_STORE_LIVE_SCAN_RESULT`

Permanently store an existing temporary Live Scan result with the selected visibility. This updates the temporary result into a durable snapshot and requires the separate urlscan.io Live Scanning entitlement; a generic urlscan Pro plan may not include it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | UUID of the temporary Live Scan result to store permanently. |
| `scanner_id` | string | Yes | Live Scanning node identifier returned by LIST_LIVE_SCANNERS. |
| `visibility` | string ("public" | "unlisted" | "private") | Yes | Visibility to apply to the permanently stored scan result. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Submit Scan

**Slug:** `URLSCANIO_SUBMIT_SCAN`

Submit a URL for asynchronous external scanning, creating persistent result state and consuming quota. Visibility defaults to public, and free accounts have no cleanup operation. Returns the scan UUID for result and asset retrieval.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | URL to scan. |
| `tags` | array | No | Up to 10 tags, each containing 1-30 characters. |
| `country` | string | No | Lowercase ISO 3166-1 alpha-2 scanner country returned by LIST_AVAILABLE_COUNTRIES. |
| `referer` | string | No | Optional Referer value for the scanned navigation. |
| `visibility` | string ("public" | "unlisted" | "private") | No | Who can discover the scan. The connected account may permit fewer visibility values. |
| `custom_agent` | string | No | Custom browser user-agent string for the scan. |
| `override_safety` | string | No | Any non-empty value disables automatic PII visibility reclassification. Use only when the caller understands the exposure risk. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Notification Channel

**Slug:** `URLSCANIO_UPDATE_CHANNEL`

Replace the complete configuration of an existing Pro notification channel. This operation can redirect external effects: active webhook channels send requests to the supplied secret URL, and active email channels send messages to the supplied recipients. Confirm the complete destination and activation settings before calling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Complete human-readable channel name required by this PUT operation. |
| `type` | string ("webhook" | "email") | Yes | Complete channel delivery type required by this PUT operation. |
| `utc_time` | string | No | Replacement scheduled UTC delivery time in 24-hour HH:MM format. |
| `frequency` | string ("live" | "hourly" | "daily") | No | Replacement notification delivery frequency. |
| `is_active` | boolean | No | Replacement active state. Setting this to true can send external webhook requests or email notifications. |
| `week_days` | array | No | Replacement delivery weekdays. |
| `channel_id` | string | Yes | Unique ID of the notification channel to replace. |
| `is_default` | boolean | No | Whether this becomes the account's default notification channel. |
| `ignore_time` | boolean | No | Whether the replacement ignores scheduled delivery timing. |
| `permissions` | array | No | Replacement team sharing permissions for the channel. |
| `webhook_url` | string | No | Secret HTTP(S) destination required for a webhook channel. It may contain an embedded access token and will receive external notifications. |
| `email_addresses` | array | No | Complete external recipient list required for an email channel. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Incident

**Slug:** `URLSCANIO_UPDATE_INCIDENT`

Replace an existing incident's monitoring configuration and runtime options. This Pro-only PUT requires observable, visibility, and the complete channel set, not only changed values. Updating it changes ongoing external scanning and can redirect or trigger future channel alerts; confirm the complete replacement configuration before calling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `channels` | array | Yes | Complete notification channel ID set. Replacing it changes where future incident alerts are delivered. |
| `countries` | array | No | Optional ISO 3166-1 country codes from which incident scans run. |
| `extra_path` | string | No | Optional path appended to hostname-type incident scans. |
| `observable` | string | Yes | Complete hostname, domain, IP address, or URL to monitor. Changing it redirects the incident's ongoing scans. |
| `visibility` | string ("unlisted" | "private") | Yes | Complete visibility for scans created by this incident. |
| `incident_id` | string | Yes | Unique ID of the incident whose complete monitoring configuration is replaced. |
| `user_agents` | array | No | Optional browser user agents used for the incident's ongoing scans. |
| `scan_interval` | integer | No | Optional interval in seconds between full website scans. |
| `runtime_options` | object | No | Optional replacement timing, distribution, profile, and expiry settings. Keys use the provider's documented spellings. |
| `scan_interval_mode` | string ("manual" | "automatic") | No | Optional interval control mode. In manual mode, post-suspension and post-malicious interval settings have no effect. |
| `watched_attributes` | array | No | Optional incident attributes whose changes create monitored states and alerts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Scan Visibility

**Slug:** `URLSCANIO_UPDATE_RESULT_VISIBILITY`

Change the visibility of a scan owned by the connected user or team. This operation requires a paid urlscan Pro entitlement and is contract-only, not live verified. Use DELETE_RESULT for permanent deletion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scan_id` | string | Yes | Owned scan UUID whose visibility should be changed. |
| `visibility` | string ("public" | "unlisted" | "private") | Yes | New public, unlisted, or private visibility for the scan. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Saved Search

**Slug:** `URLSCANIO_UPDATE_SAVED_SEARCH`

Replace the complete definition and metadata of an existing saved search. This PUT operation requires urlscan Pro saved-search access and write permission; the hostnames datasource may require an additional entitlement.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tlp` | string ("red" | "amber+strict" | "amber" | "green" | "clear") | No | Optional replacement Traffic Light Protocol marking. |
| `name` | string | Yes | Complete human-readable name required by the replacement operation. |
| `query` | string | Yes | Complete urlscan.io Search API query required by the replacement operation. |
| `search_id` | string | Yes | Unique ID of the saved search to replace. |
| `user_tags` | array | No | Optional replacement user-defined tags applied to matching items. |
| `datasource` | string ("hostnames" | "scans") | Yes | Complete datasource value required by the replacement operation. |
| `description` | string | No | Optional replacement short description. |
| `permissions` | array | No | Optional replacement team or public sharing permissions. |
| `long_description` | string | No | Optional replacement detailed description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Alert Subscription

**Slug:** `URLSCANIO_UPDATE_SUBSCRIPTION`

Replace the complete configuration of an existing alert subscription. This Pro-only PUT requires every mandatory field, not only changed values. It has external notification side effects: activating the subscription or changing recipients, channels, webhooks, or incident settings can send notifications or create incidents. Confirm the complete replacement configuration before calling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Complete human-readable subscription name required by this PUT operation. |
| `frequency` | string ("live" | "hourly" | "daily") | Yes | Complete evaluation and delivery frequency required by this PUT operation. |
| `is_active` | boolean | Yes | Complete active state. Setting this to true can cause external email, channel, webhook, or incident notifications. |
| `week_days` | array | No | Optional replacement weekday selection. |
| `search_ids` | array | Yes | Complete saved-search ID set monitored by the replacement subscription. |
| `channel_ids` | array | No | Replacement notification channel IDs to invoke externally when matching results are delivered. |
| `description` | string | No | Optional replacement subscription description. |
| `ignore_time` | boolean | Yes | Complete setting for whether the subscription ignores provider timing constraints. |
| `permissions` | array | No | Optional replacement subscription sharing permissions. |
| `email_addresses` | array | Yes | Complete external email recipient list for subscription notifications. Changing this list can redirect future notifications. |
| `subscription_id` | string | Yes | Unique ID of the alert subscription to replace. |
| `incident_options` | object | No | Optional replacement incident notification settings. Changing these fields can cause external incident creation when the active subscription matches. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |