Skip to content

Pro

urlscan.Pro

Bases: BaseClient

urlscan.io Pro API client.

Source code in src/urlscan/pro/__init__.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
class Pro(BaseClient):
    """urlscan.io Pro API client."""

    @cached_property
    def brand(self) -> Brand:
        """Brand API client instance.

        Returns:
            Brand: Brand API client instance.

        """
        return Brand(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    @cached_property
    def channel(self) -> Channel:
        """Channel API client instance.

        Returns:
            Channel: Channel API client instance.

        """
        return Channel(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    @cached_property
    def datadump(self) -> DataDump:
        """Data dump API client instance.

        Returns:
            DataDump: Data dump API client instance.

        """
        return DataDump(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    @cached_property
    def incident(self) -> Incident:
        """Incident API client instance.

        Returns:
            Incident: Incident API client instance.

        """
        return Incident(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    @cached_property
    def livescan(self) -> LiveScan:
        """Live scan API client instance.

        Returns:
            LiveScan: Live scan API client instance.

        """
        return LiveScan(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    @cached_property
    def saved_search(self) -> SavedSearch:
        """Saved Search API client instance.

        Returns:
            SavedSearch: Saved Search API client instance.

        """
        return SavedSearch(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    @cached_property
    def subscription(self) -> Subscription:
        """Subscription API client instance.

        Returns:
            Subscription: Subscription API client instance.

        """
        return Subscription(
            api_key=self._api_key,
            base_url=self._base_url,
            user_agent=self._user_agent,
            trust_env=self._trust_env,
            timeout=self._timeout,
            proxy=self._proxy,
            verify=self._verify,
            retry=self._retry,
        )

    def structure_search(
        self,
        scan_id: str,
        *,
        q: str | None = None,
        size: int = 100,
        search_after: str | None = None,
        limit: int | None = None,
    ) -> SearchIterator:
        """Get results structurally similar to a specific scan.

        Args:
            scan_id (str): The original scan to compare to.
            q (str | None, optional): Additional query filter.
            size (int): Maximum results per call. Defaults to 100.
            search_after (str | None, optional): Parameter to iterate over older results. Defaults to None.
            limit (int | None, optional): Maximum number of results that will be returned by the iterator. Defaults to None.

        """
        return SearchIterator(
            client=self,
            path=f"/api/v1/pro/result/{scan_id}/similar/",
            q=q,
            size=size,
            search_after=search_after,
            limit=limit,
        )

    def hostname(
        self,
        hostname: str,
        *,
        size: int = 1000,
        limit: int | None = None,
        page_state: str | None = None,
    ) -> HostnameIterator:
        """Get the historical observations for a specific hostname.

        Args:
            hostname (str): The hostname to query.
            page_state (str | None, optional): Page state for pagination. Defaults to None.
            size (int, optional): Number of results returned in a search. Defaults to 1000.
            limit (int | None, optional): Maximum number of results that will be returned by the iterator. Defaults to None.

        Returns:
            HostnameIterator: Hostname iterator.

        """
        return HostnameIterator(
            client=self,
            hostname=hostname,
            size=size,
            limit=limit,
            page_state=page_state,
        )

    def download_file(
        self,
        file_hash: str,
        *,
        file: BinaryIO,
        password: str | None = None,
        filename: str | None = None,
    ):
        """Download a file by its hash.

        Examples:
            >>> from urlscan import Pro
            >>> with Pro("<your_api_key>") as pro, open("downloaded_file.zip", "wb") as f:
            ...     pro.download_file(
            ...         file_hash="<file_hash>",
            ...         file=f,
            ...     )

        Args:
            file_hash (str): The hash of the file to download.
            file (BinaryIO): File object to write to.
            password (str | None, optional): The password to use to encrypt the ZIP file. The default password is "urlscan!" if it's not provided. Defaults to None.
            filename (str | None, optional): Specify the name of the ZIP file that should be downloaded. This does not change the name of files within the ZIP archive. The default filename is {file_hash}.zip if it's not provided. Defaults to None.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/files/downloadfile

        """
        params: dict[str, str] = _compact(
            {
                "password": password,
                "filename": filename,
            }
        )
        return self.download(f"/downloads/{file_hash}", params=params, file=file)

    def get_user(self) -> dict:
        """Get information about the current user or API key making the request.

        Returns:
            dict: User information.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/generic/prousername

        """
        return self.get_json("/api/v1/pro/username")

brand cached property

Brand API client instance.

Returns:

Name Type Description
Brand Brand

Brand API client instance.

channel cached property

Channel API client instance.

Returns:

Name Type Description
Channel Channel

Channel API client instance.

datadump cached property

Data dump API client instance.

Returns:

Name Type Description
DataDump DataDump

Data dump API client instance.

incident cached property

Incident API client instance.

Returns:

Name Type Description
Incident Incident

Incident API client instance.

livescan cached property

Live scan API client instance.

Returns:

Name Type Description
LiveScan LiveScan

Live scan API client instance.

Saved Search API client instance.

Returns:

Name Type Description
SavedSearch SavedSearch

Saved Search API client instance.

subscription cached property

Subscription API client instance.

Returns:

Name Type Description
Subscription Subscription

Subscription API client instance.

download_file(file_hash, *, file, password=None, filename=None)

Download a file by its hash.

Examples:

>>> from urlscan import Pro
>>> with Pro("<your_api_key>") as pro, open("downloaded_file.zip", "wb") as f:
...     pro.download_file(
...         file_hash="<file_hash>",
...         file=f,
...     )

Parameters:

Name Type Description Default
file_hash str

The hash of the file to download.

 required
file BinaryIO

File object to write to.

 required
password str | None

The password to use to encrypt the ZIP file. The default password is "urlscan!" if it's not provided. Defaults to None.

 None
filename str | None

Specify the name of the ZIP file that should be downloaded. This does not change the name of files within the ZIP archive. The default filename is {file_hash}.zip if it's not provided. Defaults to None.

 None
Reference

https://docs.urlscan.io/apis/urlscan-openapi/files/downloadfile

Source code in src/urlscan/pro/__init__.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
def download_file(
    self,
    file_hash: str,
    *,
    file: BinaryIO,
    password: str | None = None,
    filename: str | None = None,
):
    """Download a file by its hash.

    Examples:
        >>> from urlscan import Pro
        >>> with Pro("<your_api_key>") as pro, open("downloaded_file.zip", "wb") as f:
        ...     pro.download_file(
        ...         file_hash="<file_hash>",
        ...         file=f,
        ...     )

    Args:
        file_hash (str): The hash of the file to download.
        file (BinaryIO): File object to write to.
        password (str | None, optional): The password to use to encrypt the ZIP file. The default password is "urlscan!" if it's not provided. Defaults to None.
        filename (str | None, optional): Specify the name of the ZIP file that should be downloaded. This does not change the name of files within the ZIP archive. The default filename is {file_hash}.zip if it's not provided. Defaults to None.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/files/downloadfile

    """
    params: dict[str, str] = _compact(
        {
            "password": password,
            "filename": filename,
        }
    )
    return self.download(f"/downloads/{file_hash}", params=params, file=file)

get_user()

Get information about the current user or API key making the request.

Returns:

Name Type Description
dict dict

User information.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/generic/prousername

Source code in src/urlscan/pro/__init__.py 
248
249
250
251
252
253
254
255
256
257
258
def get_user(self) -> dict:
    """Get information about the current user or API key making the request.

    Returns:
        dict: User information.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/generic/prousername

    """
    return self.get_json("/api/v1/pro/username")

hostname(hostname, *, size=1000, limit=None, page_state=None)

Get the historical observations for a specific hostname.

Parameters:

Name Type Description Default
hostname str

The hostname to query.

 required
page_state str | None

Page state for pagination. Defaults to None.

 None
size int

Number of results returned in a search. Defaults to 1000.

 1000
limit int | None

Maximum number of results that will be returned by the iterator. Defaults to None.

 None

Returns:

Name Type Description
HostnameIterator HostnameIterator

Hostname iterator.
Source code in src/urlscan/pro/__init__.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def hostname(
    self,
    hostname: str,
    *,
    size: int = 1000,
    limit: int | None = None,
    page_state: str | None = None,
) -> HostnameIterator:
    """Get the historical observations for a specific hostname.

    Args:
        hostname (str): The hostname to query.
        page_state (str | None, optional): Page state for pagination. Defaults to None.
        size (int, optional): Number of results returned in a search. Defaults to 1000.
        limit (int | None, optional): Maximum number of results that will be returned by the iterator. Defaults to None.

    Returns:
        HostnameIterator: Hostname iterator.

    """
    return HostnameIterator(
        client=self,
        hostname=hostname,
        size=size,
        limit=limit,
        page_state=page_state,
    )

Get results structurally similar to a specific scan.

Parameters:

Name Type Description Default
scan_id str

The original scan to compare to.

 required
q str | None

Additional query filter.

 None
size int

Maximum results per call. Defaults to 100.

 100
search_after str | None

Parameter to iterate over older results. Defaults to None.

 None
limit int | None

Maximum number of results that will be returned by the iterator. Defaults to None.

 None
Source code in src/urlscan/pro/__init__.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def structure_search(
    self,
    scan_id: str,
    *,
    q: str | None = None,
    size: int = 100,
    search_after: str | None = None,
    limit: int | None = None,
) -> SearchIterator:
    """Get results structurally similar to a specific scan.

    Args:
        scan_id (str): The original scan to compare to.
        q (str | None, optional): Additional query filter.
        size (int): Maximum results per call. Defaults to 100.
        search_after (str | None, optional): Parameter to iterate over older results. Defaults to None.
        limit (int | None, optional): Maximum number of results that will be returned by the iterator. Defaults to None.

    """
    return SearchIterator(
        client=self,
        path=f"/api/v1/pro/result/{scan_id}/similar/",
        q=q,
        size=size,
        search_after=search_after,
        limit=limit,
    )

urlscan.pro.Brand

Bases: BaseClient

Brand API client.

Source code in src/urlscan/pro/brand.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
class Brand(BaseClient):
    """Brand API client."""

    def get_available_brands(self) -> dict:
        """Get a list of brands that are tracked as part of urlscan's brand detection.

        Returns:
            dict: Response containing a list of brand objects.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/brands/availablebrands

        """
        return self.get_json("/api/v1/pro/availableBrands")

    def get_brands(self) -> dict:
        """Get a list of brands that we are able to detect phishing pages with the total number of detected pages and the latest hit for each brand.

        This is slower than the get_available method.

        Returns:
            dict: Response containing a list of brand object with detection statistics.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/brands/brandsummary

        """
        return self.get_json("/api/v1/pro/brands")

get_available_brands()

Get a list of brands that are tracked as part of urlscan's brand detection.

Returns:

Name Type Description
dict dict

Response containing a list of brand objects.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/brands/availablebrands

Source code in src/urlscan/pro/brand.py 
 9
10
11
12
13
14
15
16
17
18
19
def get_available_brands(self) -> dict:
    """Get a list of brands that are tracked as part of urlscan's brand detection.

    Returns:
        dict: Response containing a list of brand objects.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/brands/availablebrands

    """
    return self.get_json("/api/v1/pro/availableBrands")

get_brands()

Get a list of brands that we are able to detect phishing pages with the total number of detected pages and the latest hit for each brand.

This is slower than the get_available method.

Returns:

Name Type Description
dict dict

Response containing a list of brand object with detection statistics.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/brands/brandsummary

Source code in src/urlscan/pro/brand.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
def get_brands(self) -> dict:
    """Get a list of brands that we are able to detect phishing pages with the total number of detected pages and the latest hit for each brand.

    This is slower than the get_available method.

    Returns:
        dict: Response containing a list of brand object with detection statistics.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/brands/brandsummary

    """
    return self.get_json("/api/v1/pro/brands")

urlscan.pro.Channel

Bases: BaseClient

Client API client.

Source code in src/urlscan/pro/channel.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
class Channel(BaseClient):
    """Client API client."""

    def get_channels(self) -> dict:
        """Get a list of notification channels for the current user.

        Returns:
            dict: Object containing an array of channels.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/channels/channels

        """
        return self.get_json("/api/v1/user/channels/")

    def create(
        self,
        *,
        channel_type: ChannelTypeType,
        name: str,
        webhook_url: str | None = None,
        frequency: FrequencyType | None = None,
        email_addresses: list[str] | None = None,
        utc_time: str | None = None,
        is_active: bool | None = None,
        is_default: bool | None = None,
        ignore_time: bool | None = None,
        week_days: list[WeekDaysType] | None = None,
        permissions: list[ChannelPermissionType] | None = None,
        **kwargs: Any,
    ) -> dict:
        """Create a new channel.

        Args:
            channel_type (ChannelTypeType): Type of channel ("webhook" or "email").
            name (str): Name of the channel.
            webhook_url (str | None, optional): Webhook URL receiving notifications (required when channel_type is "webhook"). Defaults to None.
            frequency (FrequencyType | None, optional): Frequency of notifications ("live", "hourly", or "daily"). Defaults to None.
            email_addresses (list[str] | None, optional): Email addresses receiving the notifications (required when channel_type is "email"). Defaults to None.
            utc_time (str | None, optional): 24 hour UTC time that daily emails are sent (e.g. 09:00). Defaults to None.
            is_active (bool | None, optional): Whether the channel is active. Defaults to None.
            is_default (bool | None, optional): Whether the channel is the default. Defaults to None.
            ignore_time (bool | None, optional): Whether to ignore time constraints. Defaults to None.
            week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
            permissions (list[ChannelPermissionType] | None, optional): Permissions associated with this channel (team:read, team:write). Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Object containing the created channel.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/channels/channelscreate

        """
        channel: dict[str, Any] = _compact(
            _merge(
                {
                    "type": channel_type,
                    "name": name,
                    "webhookURL": webhook_url,
                    "frequency": frequency,
                    "emailAddresses": email_addresses,
                    "utcTime": utc_time,
                    "isActive": is_active,
                    "isDefault": is_default,
                    "ignoreTime": ignore_time,
                    "weekDays": week_days,
                    "permissions": permissions,
                },
                kwargs,
            )
        )
        data = {"channel": channel}

        res = self._post("/api/v1/user/channels/", json=data)
        return self._response_to_json(res)

    def get(self, channel_id: str) -> dict:
        """Get the search results for a specific notification channel.

        Args:
            channel_id (str): Channel ID.

        Returns:
            dict: Object containing the channel.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsget

        """
        return self.get_json(f"/api/v1/user/channels/{channel_id}/")

    def update(
        self,
        channel_id: str,
        *,
        channel_type: ChannelTypeType,
        name: str,
        webhook_url: str | None = None,
        frequency: FrequencyType | None = None,
        email_addresses: list[str] | None = None,
        utc_time: str | None = None,
        is_active: bool | None = None,
        is_default: bool | None = None,
        ignore_time: bool | None = None,
        week_days: list[WeekDaysType] | None = None,
        permissions: list[ChannelPermissionType] | None = None,
        **kwargs: Any,
    ) -> dict:
        """Update an existing channel.

        Args:
            channel_id (str): Channel ID.
            channel_type (ChannelTypeType): Type of channel ("webhook" or "email").
            name (str): Name of the channel.
            webhook_url (str | None, optional): Webhook URL receiving notifications (required when channel_type is "webhook"). Defaults to None.
            frequency (FrequencyType | None, optional): Frequency of notifications ("live", "hourly", or "daily"). Defaults to None.
            email_addresses (list[str] | None, optional): Email addresses receiving the notifications (required when channel_type is "email"). Defaults to None.
            utc_time (str | None, optional): 24 hour UTC time that daily emails are sent (e.g. 09:00). Defaults to None.
            is_active (bool | None, optional): Whether the channel is active. Defaults to None.
            is_default (bool | None, optional): Whether the channel is the default. Defaults to None.
            ignore_time (bool | None, optional): Whether to ignore time constraints. Defaults to None.
            week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
            permissions (list[ChannelPermissionType] | None, optional): Permissions associated with this channel (team:read, team:write). Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Object containing the updated channel.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsupdate

        """
        channel: dict[str, Any] = _compact(
            _merge(
                {
                    "type": channel_type,
                    "name": name,
                    "webhookURL": webhook_url,
                    "frequency": frequency,
                    "emailAddresses": email_addresses,
                    "utcTime": utc_time,
                    "isActive": is_active,
                    "isDefault": is_default,
                    "ignoreTime": ignore_time,
                    "weekDays": week_days,
                    "permissions": permissions,
                },
                kwargs,
            )
        )
        data = {"channel": channel}

        res = self._put(f"/api/v1/user/channels/{channel_id}/", json=data)
        return self._response_to_json(res)

create(*, channel_type, name, webhook_url=None, frequency=None, email_addresses=None, utc_time=None, is_active=None, is_default=None, ignore_time=None, week_days=None, permissions=None, **kwargs)

Create a new channel.

Parameters:

Name Type Description Default
channel_type ChannelTypeType

Type of channel ("webhook" or "email").

 required
name str

Name of the channel.

 required
webhook_url str | None

Webhook URL receiving notifications (required when channel_type is "webhook"). Defaults to None.

 None
frequency FrequencyType | None

Frequency of notifications ("live", "hourly", or "daily"). Defaults to None.

 None
email_addresses list[str] | None

Email addresses receiving the notifications (required when channel_type is "email"). Defaults to None.

 None
utc_time str | None

24 hour UTC time that daily emails are sent (e.g. 09:00). Defaults to None.

 None
is_active bool | None

Whether the channel is active. Defaults to None.

 None
is_default bool | None

Whether the channel is the default. Defaults to None.

 None
ignore_time bool | None

Whether to ignore time constraints. Defaults to None.

 None
week_days list[WeekDaysType] | None

Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.

 None
permissions list[ChannelPermissionType] | None

Permissions associated with this channel (team:read, team:write). Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Object containing the created channel.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/channels/channelscreate

Source code in src/urlscan/pro/channel.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def create(
    self,
    *,
    channel_type: ChannelTypeType,
    name: str,
    webhook_url: str | None = None,
    frequency: FrequencyType | None = None,
    email_addresses: list[str] | None = None,
    utc_time: str | None = None,
    is_active: bool | None = None,
    is_default: bool | None = None,
    ignore_time: bool | None = None,
    week_days: list[WeekDaysType] | None = None,
    permissions: list[ChannelPermissionType] | None = None,
    **kwargs: Any,
) -> dict:
    """Create a new channel.

    Args:
        channel_type (ChannelTypeType): Type of channel ("webhook" or "email").
        name (str): Name of the channel.
        webhook_url (str | None, optional): Webhook URL receiving notifications (required when channel_type is "webhook"). Defaults to None.
        frequency (FrequencyType | None, optional): Frequency of notifications ("live", "hourly", or "daily"). Defaults to None.
        email_addresses (list[str] | None, optional): Email addresses receiving the notifications (required when channel_type is "email"). Defaults to None.
        utc_time (str | None, optional): 24 hour UTC time that daily emails are sent (e.g. 09:00). Defaults to None.
        is_active (bool | None, optional): Whether the channel is active. Defaults to None.
        is_default (bool | None, optional): Whether the channel is the default. Defaults to None.
        ignore_time (bool | None, optional): Whether to ignore time constraints. Defaults to None.
        week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
        permissions (list[ChannelPermissionType] | None, optional): Permissions associated with this channel (team:read, team:write). Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Object containing the created channel.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/channels/channelscreate

    """
    channel: dict[str, Any] = _compact(
        _merge(
            {
                "type": channel_type,
                "name": name,
                "webhookURL": webhook_url,
                "frequency": frequency,
                "emailAddresses": email_addresses,
                "utcTime": utc_time,
                "isActive": is_active,
                "isDefault": is_default,
                "ignoreTime": ignore_time,
                "weekDays": week_days,
                "permissions": permissions,
            },
            kwargs,
        )
    )
    data = {"channel": channel}

    res = self._post("/api/v1/user/channels/", json=data)
    return self._response_to_json(res)

get(channel_id)

Get the search results for a specific notification channel.

Parameters:

Name Type Description Default
channel_id str

Channel ID.

 required

Returns:

Name Type Description
dict dict

Object containing the channel.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsget

Source code in src/urlscan/pro/channel.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def get(self, channel_id: str) -> dict:
    """Get the search results for a specific notification channel.

    Args:
        channel_id (str): Channel ID.

    Returns:
        dict: Object containing the channel.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsget

    """
    return self.get_json(f"/api/v1/user/channels/{channel_id}/")

get_channels()

Get a list of notification channels for the current user.

Returns:

Name Type Description
dict dict

Object containing an array of channels.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/channels/channels

Source code in src/urlscan/pro/channel.py 
18
19
20
21
22
23
24
25
26
27
28
def get_channels(self) -> dict:
    """Get a list of notification channels for the current user.

    Returns:
        dict: Object containing an array of channels.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/channels/channels

    """
    return self.get_json("/api/v1/user/channels/")

update(channel_id, *, channel_type, name, webhook_url=None, frequency=None, email_addresses=None, utc_time=None, is_active=None, is_default=None, ignore_time=None, week_days=None, permissions=None, **kwargs)

Update an existing channel.

Parameters:

Name Type Description Default
channel_id str

Channel ID.

 required
channel_type ChannelTypeType

Type of channel ("webhook" or "email").

 required
name str

Name of the channel.

 required
webhook_url str | None

Webhook URL receiving notifications (required when channel_type is "webhook"). Defaults to None.

 None
frequency FrequencyType | None

Frequency of notifications ("live", "hourly", or "daily"). Defaults to None.

 None
email_addresses list[str] | None

Email addresses receiving the notifications (required when channel_type is "email"). Defaults to None.

 None
utc_time str | None

24 hour UTC time that daily emails are sent (e.g. 09:00). Defaults to None.

 None
is_active bool | None

Whether the channel is active. Defaults to None.

 None
is_default bool | None

Whether the channel is the default. Defaults to None.

 None
ignore_time bool | None

Whether to ignore time constraints. Defaults to None.

 None
week_days list[WeekDaysType] | None

Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.

 None
permissions list[ChannelPermissionType] | None

Permissions associated with this channel (team:read, team:write). Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Object containing the updated channel.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsupdate

Source code in src/urlscan/pro/channel.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
def update(
    self,
    channel_id: str,
    *,
    channel_type: ChannelTypeType,
    name: str,
    webhook_url: str | None = None,
    frequency: FrequencyType | None = None,
    email_addresses: list[str] | None = None,
    utc_time: str | None = None,
    is_active: bool | None = None,
    is_default: bool | None = None,
    ignore_time: bool | None = None,
    week_days: list[WeekDaysType] | None = None,
    permissions: list[ChannelPermissionType] | None = None,
    **kwargs: Any,
) -> dict:
    """Update an existing channel.

    Args:
        channel_id (str): Channel ID.
        channel_type (ChannelTypeType): Type of channel ("webhook" or "email").
        name (str): Name of the channel.
        webhook_url (str | None, optional): Webhook URL receiving notifications (required when channel_type is "webhook"). Defaults to None.
        frequency (FrequencyType | None, optional): Frequency of notifications ("live", "hourly", or "daily"). Defaults to None.
        email_addresses (list[str] | None, optional): Email addresses receiving the notifications (required when channel_type is "email"). Defaults to None.
        utc_time (str | None, optional): 24 hour UTC time that daily emails are sent (e.g. 09:00). Defaults to None.
        is_active (bool | None, optional): Whether the channel is active. Defaults to None.
        is_default (bool | None, optional): Whether the channel is the default. Defaults to None.
        ignore_time (bool | None, optional): Whether to ignore time constraints. Defaults to None.
        week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
        permissions (list[ChannelPermissionType] | None, optional): Permissions associated with this channel (team:read, team:write). Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Object containing the updated channel.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsupdate

    """
    channel: dict[str, Any] = _compact(
        _merge(
            {
                "type": channel_type,
                "name": name,
                "webhookURL": webhook_url,
                "frequency": frequency,
                "emailAddresses": email_addresses,
                "utcTime": utc_time,
                "isActive": is_active,
                "isDefault": is_default,
                "ignoreTime": ignore_time,
                "weekDays": week_days,
                "permissions": permissions,
            },
            kwargs,
        )
    )
    data = {"channel": channel}

    res = self._put(f"/api/v1/user/channels/{channel_id}/", json=data)
    return self._response_to_json(res)

urlscan.pro.DataDump

Bases: BaseClient

Data dump API client.

Source code in src/urlscan/pro/datadump.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class DataDump(BaseClient):
    """Data dump API client."""

    def get_list(self, path: str) -> dict:
        """List available data dump files for a specific time window, file type, and date.

        Args:
            path (str): The data dump path. Format is /{time_window}/{file_type}/{date}/.
                        - time_window: days, hours, minutes.
                        - file_type: api, search, screenshots, dom.
                        - date: date of the data dump in YYYYMMDD format.

        Returns:
            dict: The list of data dump files.

        Examples:
            >>> from urlscan import Pro
            >>> with Pro("<your_api_key>") as client:
            ...     result = client.datadump.get_list("days/api/20260101")

        """
        return self.get_json(urljoin("/api/v1/datadump/list/", path))

    def download_file(
        self,
        path: str,
        file: BinaryIO,
    ):
        """Download the datadump file.

        Args:
            path (str): Path to API endpoint.
            file (BinaryIO): File object to write to.

        """
        return super().download(
            urljoin("/api/v1/datadump/link/", path),
            file=file,
        )

download_file(path, file)

Download the datadump file.

Parameters:

Name Type Description Default
path str

Path to API endpoint.

 required
file BinaryIO

File object to write to.

 required
Source code in src/urlscan/pro/datadump.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def download_file(
    self,
    path: str,
    file: BinaryIO,
):
    """Download the datadump file.

    Args:
        path (str): Path to API endpoint.
        file (BinaryIO): File object to write to.

    """
    return super().download(
        urljoin("/api/v1/datadump/link/", path),
        file=file,
    )

get_list(path)

List available data dump files for a specific time window, file type, and date.

Parameters:

Name Type Description Default
path str

The data dump path. Format is /{time_window}/{file_type}/{date}/. - time_window: days, hours, minutes. - file_type: api, search, screenshots, dom. - date: date of the data dump in YYYYMMDD format.

 required

Returns:

Name Type Description
dict dict

The list of data dump files.

Examples:

>>> from urlscan import Pro
>>> with Pro("<your_api_key>") as client:
...     result = client.datadump.get_list("days/api/20260101")
Source code in src/urlscan/pro/datadump.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get_list(self, path: str) -> dict:
    """List available data dump files for a specific time window, file type, and date.

    Args:
        path (str): The data dump path. Format is /{time_window}/{file_type}/{date}/.
                    - time_window: days, hours, minutes.
                    - file_type: api, search, screenshots, dom.
                    - date: date of the data dump in YYYYMMDD format.

    Returns:
        dict: The list of data dump files.

    Examples:
        >>> from urlscan import Pro
        >>> with Pro("<your_api_key>") as client:
        ...     result = client.datadump.get_list("days/api/20260101")

    """
    return self.get_json(urljoin("/api/v1/datadump/list/", path))

Note: you can use extract function in the utils module to extract a downloaded data dump file.

import os

from urlscan import Pro
from urlscan.utils import extract

with Pro("<your_api_key>") as pro:
    # get a list of hourly API data dump files
    res = pro.datadump.get_list("hours/api/20260101/")

    # download & extract them one by one
    for f in res["files"]
        path: str = f["path"]

        basename = os.path.basename(path)
        with open(basename, "wb") as file:
            pro.datadump.download_file(path, file=file)

        extract(basename, "/tmp")

urlscan.pro.HostnameIterator

Bases: BaseIterator

Hostname iterator.

Examples:

>>> from urlscan import Pro
>>> with Pro("<your_api_key>") as client:
>>>     for result in client.hostname("example.com"):
>>>         print(result["sub_id"], result["data"])
Source code in src/urlscan/pro/hostname.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class HostnameIterator(BaseIterator):
    """Hostname iterator.

    Examples:
        >>> from urlscan import Pro
        >>> with Pro("<your_api_key>") as client:
        >>>     for result in client.hostname("example.com"):
        >>>         print(result["sub_id"], result["data"])

    """

    def __init__(
        self,
        client: BaseClient,
        *,
        hostname: str,
        page_state: str | None = None,
        size: int = 1_000,
        limit: int | None = None,
    ):
        """Initialize the hostname iterator.

        Args:
            client (Client): Client.
            hostname (str): Hostname to query.
            page_state (str | None, optional): Page state for pagination. Defaults to None.
            size (int, optional): Number of results returned in a search. Defaults to 1000.
            limit (int | None, optional): Maximum number of results that will be returned by the iterator. Defaults to None.

        """
        self._client = client
        self._path = urljoin("/api/v1/hostname/", hostname)
        self._page_state = page_state
        self._size = size
        self._results: list[dict] = []
        self._limit = limit
        self._count = 0
        self._has_more: bool = True

    def _parse_response(self, data: dict) -> tuple[list[dict], str | None]:
        results: list[dict] = data["results"]
        page_state: str | None = data["pageState"]
        return results, page_state

    def _get(self):
        data = self._client.get_json(
            self._path,
            params=_compact(
                {
                    "limit": self._size,
                    "pageState": self._page_state,
                }
            ),
        )
        return self._parse_response(data)

    def __next__(self):
        """Return the next hostname observation result."""
        if self._limit and self._count >= self._limit:
            raise StopIteration()

        if len(self._results) == 0 and self._has_more:
            self._results, page_state = self._get()
            self._page_state = page_state
            self._has_more = page_state is not None

        if len(self._results) == 0:
            raise StopIteration()

        result = self._results.pop(0)
        self._count += 1
        return result

__init__(client, *, hostname, page_state=None, size=1000, limit=None)

Initialize the hostname iterator.

Parameters:

Name Type Description Default
client Client

Client.

 required
hostname str

Hostname to query.

 required
page_state str | None

Page state for pagination. Defaults to None.

 None
size int

Number of results returned in a search. Defaults to 1000.

 1000
limit int | None

Maximum number of results that will be returned by the iterator. Defaults to None.

 None
Source code in src/urlscan/pro/hostname.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def __init__(
    self,
    client: BaseClient,
    *,
    hostname: str,
    page_state: str | None = None,
    size: int = 1_000,
    limit: int | None = None,
):
    """Initialize the hostname iterator.

    Args:
        client (Client): Client.
        hostname (str): Hostname to query.
        page_state (str | None, optional): Page state for pagination. Defaults to None.
        size (int, optional): Number of results returned in a search. Defaults to 1000.
        limit (int | None, optional): Maximum number of results that will be returned by the iterator. Defaults to None.

    """
    self._client = client
    self._path = urljoin("/api/v1/hostname/", hostname)
    self._page_state = page_state
    self._size = size
    self._results: list[dict] = []
    self._limit = limit
    self._count = 0
    self._has_more: bool = True

__next__()

Return the next hostname observation result.

Source code in src/urlscan/pro/hostname.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def __next__(self):
    """Return the next hostname observation result."""
    if self._limit and self._count >= self._limit:
        raise StopIteration()

    if len(self._results) == 0 and self._has_more:
        self._results, page_state = self._get()
        self._page_state = page_state
        self._has_more = page_state is not None

    if len(self._results) == 0:
        raise StopIteration()

    result = self._results.pop(0)
    self._count += 1
    return result

urlscan.pro.Incident

Bases: BaseClient

Incident API client.

Source code in src/urlscan/pro/incident.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
class Incident(BaseClient):
    """Incident API client."""

    def create(
        self,
        *,
        observable: str,
        visibility: IncidentVisibilityType,
        channels: list[str],
        scan_interval: int | None = None,
        scan_interval_mode: ScanIntervalModeType | None = None,
        watched_attributes: list[WatchedAttributeType] | None = None,
        user_agents: list[str] | None = None,
        user_agents_per_interval: int | None = None,
        countries: list[str] | None = None,
        countries_per_interval: int | None = None,
        stop_delay_suspended: int | None = None,
        stop_delay_inactive: int | None = None,
        stop_delay_malicious: int | None = None,
        scan_interval_after_suspended: int | None = None,
        scan_interval_after_malicious: int | None = None,
        incident_profile: str | None = None,
        expire_after: int | None = None,
        **kwargs: Any,
    ) -> dict:
        """Create an incident with specific options.

        Args:
            observable (str): Hostname, domain, IP, or URL to observe.
            visibility (IncidentVisibilityType): Scan visibility ("unlisted" or "private").
            channels (list[str]): Channels subscribed to this incident.
            scan_interval (int | None, optional): Interval (seconds) between triggering full website scans. Defaults to None.
            scan_interval_mode (ScanIntervalModeType | None, optional): If this is set to manual then scan_interval_after_suspended and scan_interval_after_malicious will not have an effect ("manual" or "automatic"). Defaults to None.
            watched_attributes (list[WatchedAttributeType] | None, optional): Determine which items will be monitored for (detections, tls, dns, labels, page, meta, ip). Defaults to None.
            user_agents (list[str] | None, optional): Browser User-Agents to use during scanning. Defaults to None.
            user_agents_per_interval (int | None, optional): How many userAgents to use per scanInterval. Defaults to None.
            countries (list[str] | None, optional): List of countries to scan from as ISO-3166-1 country codes. Defaults to None.
            countries_per_interval (int | None, optional): How many countries to use per scan interval. Defaults to None.
            stop_delay_suspended (int | None, optional): When to automatically close the incident after the observable was suspended. Defaults to None.
            stop_delay_inactive (int | None, optional): When to automatically close the incident after the observable became inactive. Defaults to None.
            stop_delay_malicious (int | None, optional): When to automatically close the incident after the observable became malicious. Defaults to None.
            scan_interval_after_suspended (int | None, optional): How to change the scan interval after the observable was suspended. Defaults to None.
            scan_interval_after_malicious (int | None, optional): How to change the scan interval after the observable became malicious. Defaults to None.
            incident_profile (str | None, optional): ID of the incident profile to use when creating this incident. Defaults to None.
            expire_after (int | None, optional): Seconds until the incident will automatically be closed. Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Incident body.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/createincident

        """
        incident: dict[str, Any] = _compact(
            _merge(
                {
                    "observable": observable,
                    "visibility": visibility,
                    "channels": channels,
                    "scanInterval": scan_interval,
                    "scanIntervalMode": scan_interval_mode,
                    "watchedAttributes": watched_attributes,
                    "userAgents": user_agents,
                    "userAgentsPerInterval": user_agents_per_interval,
                    "countries": countries,
                    "countriesPerInterval": countries_per_interval,
                    "stopDelaySuspended": stop_delay_suspended,
                    "stopDelayInactive": stop_delay_inactive,
                    "stopDelayMalicious": stop_delay_malicious,
                    "scanIntervalAfterSuspended": scan_interval_after_suspended,
                    "scanIntervalAfterMalicious": scan_interval_after_malicious,
                    "incidentProfile": incident_profile,
                    "expireAfter": expire_after,
                },
                kwargs,
            )
        )
        data = {"incident": incident}

        res = self._post("/api/v1/user/incidents", json=data)
        return self._response_to_json(res)

    def get(self, incident_id: str) -> dict:
        """Get details for a specific incident.

        Args:
            incident_id (str): ID of incident.

        Returns:
            dict: Incident body.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincident

        """
        return super().get_json(f"/api/v1/user/incidents/{incident_id}")

    def update(
        self,
        incident_id: str,
        *,
        observable: str,
        visibility: IncidentVisibilityType,
        channels: list[str],
        scan_interval: int | None = None,
        scan_interval_mode: ScanIntervalModeType | None = None,
        watched_attributes: list[WatchedAttributeType] | None = None,
        user_agents: list[str] | None = None,
        user_agents_per_interval: int | None = None,
        countries: list[str] | None = None,
        countries_per_interval: int | None = None,
        stop_delay_suspended: int | None = None,
        stop_delay_inactive: int | None = None,
        stop_delay_malicious: int | None = None,
        scan_interval_after_suspended: int | None = None,
        scan_interval_after_malicious: int | None = None,
        incident_profile: str | None = None,
        expire_after: int | None = None,
        **kwargs: Any,
    ) -> dict:
        """Update specific runtime options of the incident.

        Args:
            incident_id (str): ID of incident.
            observable (str): Hostname, domain, IP, or URL to observe.
            visibility (IncidentVisibilityType): Scan visibility ("unlisted" or "private").
            channels (list[str]): Channels subscribed to this incident.
            scan_interval (int | None, optional): Interval (seconds) between triggering full website scans. Defaults to None.
            scan_interval_mode (ScanIntervalModeType | None, optional): If this is set to manual then scan_interval_after_suspended and scan_interval_after_malicious will not have an effect ("manual" or "automatic"). Defaults to None.
            watched_attributes (list[WatchedAttributeType] | None, optional): Determine which items will be monitored for (detections, tls, dns, labels, page, meta, ip). Defaults to None.
            user_agents (list[str] | None, optional): Browser User-Agents to use during scanning. Defaults to None.
            user_agents_per_interval (int | None, optional): How many userAgents to use per scanInterval. Defaults to None.
            countries (list[str] | None, optional): List of countries to scan from as ISO-3166-1 country codes. Defaults to None.
            countries_per_interval (int | None, optional): How many countries to use per scan interval. Defaults to None.
            stop_delay_suspended (int | None, optional): When to automatically close the incident after the observable was suspended. Defaults to None.
            stop_delay_inactive (int | None, optional): When to automatically close the incident after the observable became inactive. Defaults to None.
            stop_delay_malicious (int | None, optional): When to automatically close the incident after the observable became malicious. Defaults to None.
            scan_interval_after_suspended (int | None, optional): How to change the scan interval after the observable was suspended. Defaults to None.
            scan_interval_after_malicious (int | None, optional): How to change the scan interval after the observable became malicious. Defaults to None.
            incident_profile (str | None, optional): ID of the incident profile to use when creating this incident. Defaults to None.
            expire_after (int | None, optional): Seconds until the incident will automatically be closed. Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Incident body.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/updateincident

        """
        incident: dict[str, Any] = _compact(
            _merge(
                {
                    "observable": observable,
                    "visibility": visibility,
                    "channels": channels,
                    "scanInterval": scan_interval,
                    "scanIntervalMode": scan_interval_mode,
                    "watchedAttributes": watched_attributes,
                    "userAgents": user_agents,
                    "userAgentsPerInterval": user_agents_per_interval,
                    "countries": countries,
                    "countriesPerInterval": countries_per_interval,
                    "stopDelaySuspended": stop_delay_suspended,
                    "stopDelayInactive": stop_delay_inactive,
                    "stopDelayMalicious": stop_delay_malicious,
                    "scanIntervalAfterSuspended": scan_interval_after_suspended,
                    "scanIntervalAfterMalicious": scan_interval_after_malicious,
                    "incidentProfile": incident_profile,
                    "expireAfter": expire_after,
                },
                kwargs,
            )
        )
        data = {"incident": incident}

        res = self._put(f"/api/v1/user/incidents/{incident_id}", json=data)
        return self._response_to_json(res)

    def close(self, *, incident_id: str) -> dict:
        """Close (stop) the incident.

        Args:
            incident_id (str): ID of incident.

        Returns:
            dict: Response confirming closure.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/closeincident

        """
        res = self._put(f"/api/v1/user/incidents/{incident_id}/close", json={})
        return self._response_to_json(res)

    def restart(self, incident_id: str) -> dict:
        """Restart a closed incident.

        Automatically extends the incident expireAt. Starts with new incident states.

        Args:
            incident_id (str): ID of incident.

        Returns:
            dict: Response confirming restart.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/restartincident

        """
        res = self._put(f"/api/v1/user/incidents/{incident_id}/restart", json={})
        return self._response_to_json(res)

    def copy(self, incident_id: str) -> dict:
        """Copy an incident without its history.

        Args:
            incident_id (str): ID of incident.

        Returns:
            dict: Incident body.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/copyincident

        """
        res = self._post(f"/api/v1/user/incidents/{incident_id}/copy", json={})
        return self._response_to_json(res)

    def fork(self, incident_id: str) -> dict:
        """Copy an incident along with its history (incident states).

        Args:
            incident_id (str): ID of incident.

        Returns:
            dict: Incident body.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/forkincident

        """
        res = self._post(f"/api/v1/user/incidents/{incident_id}/fork", json={})
        return self._response_to_json(res)

    def get_watchable_attributes(self) -> dict:
        """Get the list of attributes which can be supplied to the watchedAttributes property of the incident.

        Returns:
            dict: List of watchable attributes.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/getwatchableattributes

        """
        return self.get_json("/api/v1/user/watchableAttributes")

    def get_states(self, incident_id: str) -> dict:
        """Retrieve individual incident states of an incident.

        Args:
            incident_id (str): ID of incident.

        Returns:
            dict: Incident states.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincidentstates

        """
        return self.get_json(f"/api/v1/user/incidentstates/{incident_id}/")

close(*, incident_id)

Close (stop) the incident.

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required

Returns:

Name Type Description
dict dict

Response confirming closure.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/closeincident

Source code in src/urlscan/pro/incident.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
def close(self, *, incident_id: str) -> dict:
    """Close (stop) the incident.

    Args:
        incident_id (str): ID of incident.

    Returns:
        dict: Response confirming closure.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/closeincident

    """
    res = self._put(f"/api/v1/user/incidents/{incident_id}/close", json={})
    return self._response_to_json(res)

copy(incident_id)

Copy an incident without its history.

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required

Returns:

Name Type Description
dict dict

Incident body.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/copyincident

Source code in src/urlscan/pro/incident.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
def copy(self, incident_id: str) -> dict:
    """Copy an incident without its history.

    Args:
        incident_id (str): ID of incident.

    Returns:
        dict: Incident body.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/copyincident

    """
    res = self._post(f"/api/v1/user/incidents/{incident_id}/copy", json={})
    return self._response_to_json(res)

create(*, observable, visibility, channels, scan_interval=None, scan_interval_mode=None, watched_attributes=None, user_agents=None, user_agents_per_interval=None, countries=None, countries_per_interval=None, stop_delay_suspended=None, stop_delay_inactive=None, stop_delay_malicious=None, scan_interval_after_suspended=None, scan_interval_after_malicious=None, incident_profile=None, expire_after=None, **kwargs)

Create an incident with specific options.

Parameters:

Name Type Description Default
observable str

Hostname, domain, IP, or URL to observe.

 required
visibility IncidentVisibilityType

Scan visibility ("unlisted" or "private").

 required
channels list[str]

Channels subscribed to this incident.

 required
scan_interval int | None

Interval (seconds) between triggering full website scans. Defaults to None.

 None
scan_interval_mode ScanIntervalModeType | None

If this is set to manual then scan_interval_after_suspended and scan_interval_after_malicious will not have an effect ("manual" or "automatic"). Defaults to None.

 None
watched_attributes list[WatchedAttributeType] | None

Determine which items will be monitored for (detections, tls, dns, labels, page, meta, ip). Defaults to None.

 None
user_agents list[str] | None

Browser User-Agents to use during scanning. Defaults to None.

 None
user_agents_per_interval int | None

How many userAgents to use per scanInterval. Defaults to None.

 None
countries list[str] | None

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

 None
countries_per_interval int | None

How many countries to use per scan interval. Defaults to None.

 None
stop_delay_suspended int | None

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

 None
stop_delay_inactive int | None

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

 None
stop_delay_malicious int | None

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

 None
scan_interval_after_suspended int | None

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

 None
scan_interval_after_malicious int | None

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

 None
incident_profile str | None

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

 None
expire_after int | None

Seconds until the incident will automatically be closed. Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Incident body.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/createincident

Source code in src/urlscan/pro/incident.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def create(
    self,
    *,
    observable: str,
    visibility: IncidentVisibilityType,
    channels: list[str],
    scan_interval: int | None = None,
    scan_interval_mode: ScanIntervalModeType | None = None,
    watched_attributes: list[WatchedAttributeType] | None = None,
    user_agents: list[str] | None = None,
    user_agents_per_interval: int | None = None,
    countries: list[str] | None = None,
    countries_per_interval: int | None = None,
    stop_delay_suspended: int | None = None,
    stop_delay_inactive: int | None = None,
    stop_delay_malicious: int | None = None,
    scan_interval_after_suspended: int | None = None,
    scan_interval_after_malicious: int | None = None,
    incident_profile: str | None = None,
    expire_after: int | None = None,
    **kwargs: Any,
) -> dict:
    """Create an incident with specific options.

    Args:
        observable (str): Hostname, domain, IP, or URL to observe.
        visibility (IncidentVisibilityType): Scan visibility ("unlisted" or "private").
        channels (list[str]): Channels subscribed to this incident.
        scan_interval (int | None, optional): Interval (seconds) between triggering full website scans. Defaults to None.
        scan_interval_mode (ScanIntervalModeType | None, optional): If this is set to manual then scan_interval_after_suspended and scan_interval_after_malicious will not have an effect ("manual" or "automatic"). Defaults to None.
        watched_attributes (list[WatchedAttributeType] | None, optional): Determine which items will be monitored for (detections, tls, dns, labels, page, meta, ip). Defaults to None.
        user_agents (list[str] | None, optional): Browser User-Agents to use during scanning. Defaults to None.
        user_agents_per_interval (int | None, optional): How many userAgents to use per scanInterval. Defaults to None.
        countries (list[str] | None, optional): List of countries to scan from as ISO-3166-1 country codes. Defaults to None.
        countries_per_interval (int | None, optional): How many countries to use per scan interval. Defaults to None.
        stop_delay_suspended (int | None, optional): When to automatically close the incident after the observable was suspended. Defaults to None.
        stop_delay_inactive (int | None, optional): When to automatically close the incident after the observable became inactive. Defaults to None.
        stop_delay_malicious (int | None, optional): When to automatically close the incident after the observable became malicious. Defaults to None.
        scan_interval_after_suspended (int | None, optional): How to change the scan interval after the observable was suspended. Defaults to None.
        scan_interval_after_malicious (int | None, optional): How to change the scan interval after the observable became malicious. Defaults to None.
        incident_profile (str | None, optional): ID of the incident profile to use when creating this incident. Defaults to None.
        expire_after (int | None, optional): Seconds until the incident will automatically be closed. Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Incident body.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/createincident

    """
    incident: dict[str, Any] = _compact(
        _merge(
            {
                "observable": observable,
                "visibility": visibility,
                "channels": channels,
                "scanInterval": scan_interval,
                "scanIntervalMode": scan_interval_mode,
                "watchedAttributes": watched_attributes,
                "userAgents": user_agents,
                "userAgentsPerInterval": user_agents_per_interval,
                "countries": countries,
                "countriesPerInterval": countries_per_interval,
                "stopDelaySuspended": stop_delay_suspended,
                "stopDelayInactive": stop_delay_inactive,
                "stopDelayMalicious": stop_delay_malicious,
                "scanIntervalAfterSuspended": scan_interval_after_suspended,
                "scanIntervalAfterMalicious": scan_interval_after_malicious,
                "incidentProfile": incident_profile,
                "expireAfter": expire_after,
            },
            kwargs,
        )
    )
    data = {"incident": incident}

    res = self._post("/api/v1/user/incidents", json=data)
    return self._response_to_json(res)

fork(incident_id)

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

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required

Returns:

Name Type Description
dict dict

Incident body.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/forkincident

Source code in src/urlscan/pro/incident.py 
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
def fork(self, incident_id: str) -> dict:
    """Copy an incident along with its history (incident states).

    Args:
        incident_id (str): ID of incident.

    Returns:
        dict: Incident body.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/forkincident

    """
    res = self._post(f"/api/v1/user/incidents/{incident_id}/fork", json={})
    return self._response_to_json(res)

get(incident_id)

Get details for a specific incident.

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required

Returns:

Name Type Description
dict dict

Incident body.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincident

Source code in src/urlscan/pro/incident.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def get(self, incident_id: str) -> dict:
    """Get details for a specific incident.

    Args:
        incident_id (str): ID of incident.

    Returns:
        dict: Incident body.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincident

    """
    return super().get_json(f"/api/v1/user/incidents/{incident_id}")

get_states(incident_id)

Retrieve individual incident states of an incident.

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required

Returns:

Name Type Description
dict dict

Incident states.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincidentstates

Source code in src/urlscan/pro/incident.py 
272
273
274
275
276
277
278
279
280
281
282
283
284
285
def get_states(self, incident_id: str) -> dict:
    """Retrieve individual incident states of an incident.

    Args:
        incident_id (str): ID of incident.

    Returns:
        dict: Incident states.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincidentstates

    """
    return self.get_json(f"/api/v1/user/incidentstates/{incident_id}/")

get_watchable_attributes()

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

Returns:

Name Type Description
dict dict

List of watchable attributes.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/getwatchableattributes

Source code in src/urlscan/pro/incident.py 
260
261
262
263
264
265
266
267
268
269
270
def get_watchable_attributes(self) -> dict:
    """Get the list of attributes which can be supplied to the watchedAttributes property of the incident.

    Returns:
        dict: List of watchable attributes.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/getwatchableattributes

    """
    return self.get_json("/api/v1/user/watchableAttributes")

restart(incident_id)

Restart a closed incident.

Automatically extends the incident expireAt. Starts with new incident states.

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required

Returns:

Name Type Description
dict dict

Response confirming restart.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/restartincident

Source code in src/urlscan/pro/incident.py 
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
def restart(self, incident_id: str) -> dict:
    """Restart a closed incident.

    Automatically extends the incident expireAt. Starts with new incident states.

    Args:
        incident_id (str): ID of incident.

    Returns:
        dict: Response confirming restart.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/restartincident

    """
    res = self._put(f"/api/v1/user/incidents/{incident_id}/restart", json={})
    return self._response_to_json(res)

update(incident_id, *, observable, visibility, channels, scan_interval=None, scan_interval_mode=None, watched_attributes=None, user_agents=None, user_agents_per_interval=None, countries=None, countries_per_interval=None, stop_delay_suspended=None, stop_delay_inactive=None, stop_delay_malicious=None, scan_interval_after_suspended=None, scan_interval_after_malicious=None, incident_profile=None, expire_after=None, **kwargs)

Update specific runtime options of the incident.

Parameters:

Name Type Description Default
incident_id str

ID of incident.

 required
observable str

Hostname, domain, IP, or URL to observe.

 required
visibility IncidentVisibilityType

Scan visibility ("unlisted" or "private").

 required
channels list[str]

Channels subscribed to this incident.

 required
scan_interval int | None

Interval (seconds) between triggering full website scans. Defaults to None.

 None
scan_interval_mode ScanIntervalModeType | None

If this is set to manual then scan_interval_after_suspended and scan_interval_after_malicious will not have an effect ("manual" or "automatic"). Defaults to None.

 None
watched_attributes list[WatchedAttributeType] | None

Determine which items will be monitored for (detections, tls, dns, labels, page, meta, ip). Defaults to None.

 None
user_agents list[str] | None

Browser User-Agents to use during scanning. Defaults to None.

 None
user_agents_per_interval int | None

How many userAgents to use per scanInterval. Defaults to None.

 None
countries list[str] | None

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

 None
countries_per_interval int | None

How many countries to use per scan interval. Defaults to None.

 None
stop_delay_suspended int | None

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

 None
stop_delay_inactive int | None

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

 None
stop_delay_malicious int | None

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

 None
scan_interval_after_suspended int | None

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

 None
scan_interval_after_malicious int | None

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

 None
incident_profile str | None

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

 None
expire_after int | None

Seconds until the incident will automatically be closed. Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Incident body.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/incidents/updateincident

Source code in src/urlscan/pro/incident.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
def update(
    self,
    incident_id: str,
    *,
    observable: str,
    visibility: IncidentVisibilityType,
    channels: list[str],
    scan_interval: int | None = None,
    scan_interval_mode: ScanIntervalModeType | None = None,
    watched_attributes: list[WatchedAttributeType] | None = None,
    user_agents: list[str] | None = None,
    user_agents_per_interval: int | None = None,
    countries: list[str] | None = None,
    countries_per_interval: int | None = None,
    stop_delay_suspended: int | None = None,
    stop_delay_inactive: int | None = None,
    stop_delay_malicious: int | None = None,
    scan_interval_after_suspended: int | None = None,
    scan_interval_after_malicious: int | None = None,
    incident_profile: str | None = None,
    expire_after: int | None = None,
    **kwargs: Any,
) -> dict:
    """Update specific runtime options of the incident.

    Args:
        incident_id (str): ID of incident.
        observable (str): Hostname, domain, IP, or URL to observe.
        visibility (IncidentVisibilityType): Scan visibility ("unlisted" or "private").
        channels (list[str]): Channels subscribed to this incident.
        scan_interval (int | None, optional): Interval (seconds) between triggering full website scans. Defaults to None.
        scan_interval_mode (ScanIntervalModeType | None, optional): If this is set to manual then scan_interval_after_suspended and scan_interval_after_malicious will not have an effect ("manual" or "automatic"). Defaults to None.
        watched_attributes (list[WatchedAttributeType] | None, optional): Determine which items will be monitored for (detections, tls, dns, labels, page, meta, ip). Defaults to None.
        user_agents (list[str] | None, optional): Browser User-Agents to use during scanning. Defaults to None.
        user_agents_per_interval (int | None, optional): How many userAgents to use per scanInterval. Defaults to None.
        countries (list[str] | None, optional): List of countries to scan from as ISO-3166-1 country codes. Defaults to None.
        countries_per_interval (int | None, optional): How many countries to use per scan interval. Defaults to None.
        stop_delay_suspended (int | None, optional): When to automatically close the incident after the observable was suspended. Defaults to None.
        stop_delay_inactive (int | None, optional): When to automatically close the incident after the observable became inactive. Defaults to None.
        stop_delay_malicious (int | None, optional): When to automatically close the incident after the observable became malicious. Defaults to None.
        scan_interval_after_suspended (int | None, optional): How to change the scan interval after the observable was suspended. Defaults to None.
        scan_interval_after_malicious (int | None, optional): How to change the scan interval after the observable became malicious. Defaults to None.
        incident_profile (str | None, optional): ID of the incident profile to use when creating this incident. Defaults to None.
        expire_after (int | None, optional): Seconds until the incident will automatically be closed. Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Incident body.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/incidents/updateincident

    """
    incident: dict[str, Any] = _compact(
        _merge(
            {
                "observable": observable,
                "visibility": visibility,
                "channels": channels,
                "scanInterval": scan_interval,
                "scanIntervalMode": scan_interval_mode,
                "watchedAttributes": watched_attributes,
                "userAgents": user_agents,
                "userAgentsPerInterval": user_agents_per_interval,
                "countries": countries,
                "countriesPerInterval": countries_per_interval,
                "stopDelaySuspended": stop_delay_suspended,
                "stopDelayInactive": stop_delay_inactive,
                "stopDelayMalicious": stop_delay_malicious,
                "scanIntervalAfterSuspended": scan_interval_after_suspended,
                "scanIntervalAfterMalicious": scan_interval_after_malicious,
                "incidentProfile": incident_profile,
                "expireAfter": expire_after,
            },
            kwargs,
        )
    )
    data = {"incident": incident}

    res = self._put(f"/api/v1/user/incidents/{incident_id}", json=data)
    return self._response_to_json(res)

urlscan.pro.LiveScan

Bases: BaseClient

Live scanning API client.

Source code in src/urlscan/pro/livescan.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
class LiveScan(BaseClient):
    """Live scanning API client."""

    def get_scanners(self) -> dict:
        """Get a list of available Live Scanning nodes along with their current metadata.

        Returns:
            dict: List of available scanners with metadata.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscanners

        """
        return self.get_json("/api/v1/livescan/scanners/")

    def task(
        self,
        url: str,
        *,
        scanner_id: str,
        visibility: VisibilityType | None = None,
        page_timeout: int | None = None,
        capture_delay: int | None = None,
        extra_headers: dict[str, str] | None = None,
        enable_features: list[str] | None = None,
        disable_features: list[str] | None = None,
        **kwargs: Any,
    ) -> dict:
        """Task a URL to be scanned.

        The HTTP request will return with the scan UUID immediately and then it is your responsibility to poll the result resource type until the scan has finished.

        Args:
            url (str): URL to scan.
            scanner_id (str): Scanner ID (e.g., "de01" for Germany).
            visibility (VisibilityType | None, optional): Visibility of the scan. Defaults to None.
            page_timeout (int | None, optional): Time to wait for the whole scan process (in ms). Defaults to None.
            capture_delay (int | None, optional): Delay after page load before capturing (in ms). Defaults to None.
            extra_headers (dict[str, str] | None, optional): Extra HTTP headers. Defaults to None.
            enable_features (list[str] | None, optional): Features to enable. Defaults to None.
            disable_features (list[str] | None, optional): Features to disable. Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Response containing the scan UUID.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescantask

        """
        task: dict[str, Any] = _compact(
            {
                "url": url,
                "visibility": visibility,
            }
        )
        scanner: dict[str, Any] = _compact(
            _merge(
                {
                    "pageTimeout": page_timeout,
                    "captureDelay": capture_delay,
                    "extraHeaders": extra_headers,
                    "enableFeatures": enable_features,
                    "disableFeatures": disable_features,
                },
                kwargs,
            )
        )
        data: dict[str, Any] = {"task": task, "scanner": scanner}

        res = self._post(f"/api/v1/livescan/{scanner_id}/task/", json=data)
        return self._response_to_json(res)

    def scan(
        self,
        url: str,
        *,
        scanner_id: str,
        visibility: VisibilityType | None = None,
        page_timeout: int | None = None,
        capture_delay: int | None = None,
        extra_headers: dict[str, str] | None = None,
        enable_features: list[str] | None = None,
        disable_features: list[str] | None = None,
        **kwargs: Any,
    ) -> dict:
        """Task a URL to be scanned. The HTTP request will block until the scan has finished.

        Args:
            url (str): URL to scan.
            scanner_id (str): Scanner ID (e.g., "de01" for Germany).
            visibility (VisibilityType | None, optional): Visibility of the scan. Defaults to None.
            page_timeout (int | None, optional): Time to wait for the whole scan process (in ms). Defaults to None.
            capture_delay (int | None, optional): Delay after page load before capturing (in ms). Defaults to None.
            extra_headers (dict[str, str] | None, optional): Extra HTTP headers. Defaults to None.
            enable_features (list[str] | None, optional): Features to enable. Defaults to None.
            disable_features (list[str] | None, optional): Features to disable. Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Response containing the scan UUID.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscan

        """
        task: dict[str, Any] = _compact(
            {
                "url": url,
                "visibility": visibility,
            }
        )
        scanner: dict[str, Any] = _compact(
            _merge(
                {
                    "pageTimeout": page_timeout,
                    "captureDelay": capture_delay,
                    "extraHeaders": extra_headers,
                    "enableFeatures": enable_features,
                    "disableFeatures": disable_features,
                },
                kwargs,
            )
        )
        data: dict[str, Any] = {"task": task, "scanner": scanner}

        res = self._post(f"/api/v1/livescan/{scanner_id}/scan/", json=data)
        return self._response_to_json(res)

    def get_resource(
        self,
        *,
        scanner_id: str,
        resource_type: LiveScanResourceType,
        resource_id: str,
    ) -> Any:
        """Retrieve the resource for a particular scan ID or SHA256 from this live scanner.

        Args:
            scanner_id (str): Scanner ID (e.g., "de01" for Germany).
            resource_type (LiveScanResourceType): Type of resource ("result", "screenshot", "dom", "response", or "download").
            resource_id (str): Resource ID. For result/screenshot/dom: UUID of the scan. For response/download: SHA256 of the resource.

        Returns:
            Any: Resource content. Returns dict for "result", str for "dom", bytes for binary resources.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescangetresource

        """
        path = f"/api/v1/livescan/{scanner_id}/{resource_type}/{resource_id}"

        if resource_type == "result":
            return self.get_json(path)

        if resource_type in ("screenshot", "response", "download"):
            return self.get_content(path)

        if resource_type == "dom":
            return self.get_text(path)

        return self._get(path)

    def store(
        self,
        *,
        scanner_id: str,
        scan_id: str,
        visibility: VisibilityType,
    ) -> dict:
        """Store the temporary scan as a permanent snapshot on urlscan.io.

        Args:
            scanner_id (str): Scanner ID (e.g., "de01" for Germany).
            scan_id (str): Scan UUID.
            visibility (VisibilityType): Visibility for the stored scan ("public", "private", or "unlisted").

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanstore

        """
        data = {"task": {"visibility": visibility}}
        res = self._put(f"/api/v1/livescan/{scanner_id}/{scan_id}/", json=data)
        return self._response_to_json(res)

    def purge(
        self,
        *,
        scanner_id: str,
        scan_id: str,
    ) -> dict:
        """Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes.

        Args:
            scanner_id (str): Scanner ID (e.g., "de01" for Germany).
            scan_id (str): Scan UUID.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescandiscard

        """
        res = self._delete(f"/api/v1/livescan/{scanner_id}/{scan_id}/")
        return self._response_to_json(res)

get_resource(*, scanner_id, resource_type, resource_id)

Retrieve the resource for a particular scan ID or SHA256 from this live scanner.

Parameters:

Name Type Description Default
scanner_id str

Scanner ID (e.g., "de01" for Germany).

 required
resource_type LiveScanResourceType

Type of resource ("result", "screenshot", "dom", "response", or "download").

 required
resource_id str

Resource ID. For result/screenshot/dom: UUID of the scan. For response/download: SHA256 of the resource.

 required

Returns:

Name Type Description
Any Any

Resource content. Returns dict for "result", str for "dom", bytes for binary resources.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescangetresource

Source code in src/urlscan/pro/livescan.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def get_resource(
    self,
    *,
    scanner_id: str,
    resource_type: LiveScanResourceType,
    resource_id: str,
) -> Any:
    """Retrieve the resource for a particular scan ID or SHA256 from this live scanner.

    Args:
        scanner_id (str): Scanner ID (e.g., "de01" for Germany).
        resource_type (LiveScanResourceType): Type of resource ("result", "screenshot", "dom", "response", or "download").
        resource_id (str): Resource ID. For result/screenshot/dom: UUID of the scan. For response/download: SHA256 of the resource.

    Returns:
        Any: Resource content. Returns dict for "result", str for "dom", bytes for binary resources.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescangetresource

    """
    path = f"/api/v1/livescan/{scanner_id}/{resource_type}/{resource_id}"

    if resource_type == "result":
        return self.get_json(path)

    if resource_type in ("screenshot", "response", "download"):
        return self.get_content(path)

    if resource_type == "dom":
        return self.get_text(path)

    return self._get(path)

get_scanners()

Get a list of available Live Scanning nodes along with their current metadata.

Returns:

Name Type Description
dict dict

List of available scanners with metadata.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscanners

Source code in src/urlscan/pro/livescan.py 
13
14
15
16
17
18
19
20
21
22
23
def get_scanners(self) -> dict:
    """Get a list of available Live Scanning nodes along with their current metadata.

    Returns:
        dict: List of available scanners with metadata.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscanners

    """
    return self.get_json("/api/v1/livescan/scanners/")

purge(*, scanner_id, scan_id)

Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes.

Parameters:

Name Type Description Default
scanner_id str

Scanner ID (e.g., "de01" for Germany).

 required
scan_id str

Scan UUID.

 required
Reference

https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescandiscard

Source code in src/urlscan/pro/livescan.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def purge(
    self,
    *,
    scanner_id: str,
    scan_id: str,
) -> dict:
    """Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes.

    Args:
        scanner_id (str): Scanner ID (e.g., "de01" for Germany).
        scan_id (str): Scan UUID.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescandiscard

    """
    res = self._delete(f"/api/v1/livescan/{scanner_id}/{scan_id}/")
    return self._response_to_json(res)

scan(url, *, scanner_id, visibility=None, page_timeout=None, capture_delay=None, extra_headers=None, enable_features=None, disable_features=None, **kwargs)

Task a URL to be scanned. The HTTP request will block until the scan has finished.

Parameters:

Name Type Description Default
url str

URL to scan.

 required
scanner_id str

Scanner ID (e.g., "de01" for Germany).

 required
visibility VisibilityType | None

Visibility of the scan. Defaults to None.

 None
page_timeout int | None

Time to wait for the whole scan process (in ms). Defaults to None.

 None
capture_delay int | None

Delay after page load before capturing (in ms). Defaults to None.

 None
extra_headers dict[str, str] | None

Extra HTTP headers. Defaults to None.

 None
enable_features list[str] | None

Features to enable. Defaults to None.

 None
disable_features list[str] | None

Features to disable. Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Response containing the scan UUID.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscan

Source code in src/urlscan/pro/livescan.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def scan(
    self,
    url: str,
    *,
    scanner_id: str,
    visibility: VisibilityType | None = None,
    page_timeout: int | None = None,
    capture_delay: int | None = None,
    extra_headers: dict[str, str] | None = None,
    enable_features: list[str] | None = None,
    disable_features: list[str] | None = None,
    **kwargs: Any,
) -> dict:
    """Task a URL to be scanned. The HTTP request will block until the scan has finished.

    Args:
        url (str): URL to scan.
        scanner_id (str): Scanner ID (e.g., "de01" for Germany).
        visibility (VisibilityType | None, optional): Visibility of the scan. Defaults to None.
        page_timeout (int | None, optional): Time to wait for the whole scan process (in ms). Defaults to None.
        capture_delay (int | None, optional): Delay after page load before capturing (in ms). Defaults to None.
        extra_headers (dict[str, str] | None, optional): Extra HTTP headers. Defaults to None.
        enable_features (list[str] | None, optional): Features to enable. Defaults to None.
        disable_features (list[str] | None, optional): Features to disable. Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Response containing the scan UUID.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscan

    """
    task: dict[str, Any] = _compact(
        {
            "url": url,
            "visibility": visibility,
        }
    )
    scanner: dict[str, Any] = _compact(
        _merge(
            {
                "pageTimeout": page_timeout,
                "captureDelay": capture_delay,
                "extraHeaders": extra_headers,
                "enableFeatures": enable_features,
                "disableFeatures": disable_features,
            },
            kwargs,
        )
    )
    data: dict[str, Any] = {"task": task, "scanner": scanner}

    res = self._post(f"/api/v1/livescan/{scanner_id}/scan/", json=data)
    return self._response_to_json(res)

store(*, scanner_id, scan_id, visibility)

Store the temporary scan as a permanent snapshot on urlscan.io.

Parameters:

Name Type Description Default
scanner_id str

Scanner ID (e.g., "de01" for Germany).

 required
scan_id str

Scan UUID.

 required
visibility VisibilityType

Visibility for the stored scan ("public", "private", or "unlisted").

 required
Reference

https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanstore

Source code in src/urlscan/pro/livescan.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def store(
    self,
    *,
    scanner_id: str,
    scan_id: str,
    visibility: VisibilityType,
) -> dict:
    """Store the temporary scan as a permanent snapshot on urlscan.io.

    Args:
        scanner_id (str): Scanner ID (e.g., "de01" for Germany).
        scan_id (str): Scan UUID.
        visibility (VisibilityType): Visibility for the stored scan ("public", "private", or "unlisted").

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanstore

    """
    data = {"task": {"visibility": visibility}}
    res = self._put(f"/api/v1/livescan/{scanner_id}/{scan_id}/", json=data)
    return self._response_to_json(res)

task(url, *, scanner_id, visibility=None, page_timeout=None, capture_delay=None, extra_headers=None, enable_features=None, disable_features=None, **kwargs)

Task a URL to be scanned.

The HTTP request will return with the scan UUID immediately and then it is your responsibility to poll the result resource type until the scan has finished.

Parameters:

Name Type Description Default
url str

URL to scan.

 required
scanner_id str

Scanner ID (e.g., "de01" for Germany).

 required
visibility VisibilityType | None

Visibility of the scan. Defaults to None.

 None
page_timeout int | None

Time to wait for the whole scan process (in ms). Defaults to None.

 None
capture_delay int | None

Delay after page load before capturing (in ms). Defaults to None.

 None
extra_headers dict[str, str] | None

Extra HTTP headers. Defaults to None.

 None
enable_features list[str] | None

Features to enable. Defaults to None.

 None
disable_features list[str] | None

Features to disable. Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Response containing the scan UUID.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescantask

Source code in src/urlscan/pro/livescan.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def task(
    self,
    url: str,
    *,
    scanner_id: str,
    visibility: VisibilityType | None = None,
    page_timeout: int | None = None,
    capture_delay: int | None = None,
    extra_headers: dict[str, str] | None = None,
    enable_features: list[str] | None = None,
    disable_features: list[str] | None = None,
    **kwargs: Any,
) -> dict:
    """Task a URL to be scanned.

    The HTTP request will return with the scan UUID immediately and then it is your responsibility to poll the result resource type until the scan has finished.

    Args:
        url (str): URL to scan.
        scanner_id (str): Scanner ID (e.g., "de01" for Germany).
        visibility (VisibilityType | None, optional): Visibility of the scan. Defaults to None.
        page_timeout (int | None, optional): Time to wait for the whole scan process (in ms). Defaults to None.
        capture_delay (int | None, optional): Delay after page load before capturing (in ms). Defaults to None.
        extra_headers (dict[str, str] | None, optional): Extra HTTP headers. Defaults to None.
        enable_features (list[str] | None, optional): Features to enable. Defaults to None.
        disable_features (list[str] | None, optional): Features to disable. Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Response containing the scan UUID.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescantask

    """
    task: dict[str, Any] = _compact(
        {
            "url": url,
            "visibility": visibility,
        }
    )
    scanner: dict[str, Any] = _compact(
        _merge(
            {
                "pageTimeout": page_timeout,
                "captureDelay": capture_delay,
                "extraHeaders": extra_headers,
                "enableFeatures": enable_features,
                "disableFeatures": disable_features,
            },
            kwargs,
        )
    )
    data: dict[str, Any] = {"task": task, "scanner": scanner}

    res = self._post(f"/api/v1/livescan/{scanner_id}/task/", json=data)
    return self._response_to_json(res)

urlscan.pro.SavedSearch

Bases: BaseClient

Saved Search API client.

Source code in src/urlscan/pro/saved_search.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
class SavedSearch(BaseClient):
    """Saved Search API client."""

    def get_list(self) -> dict:
        """Get a list of Saved Searches for the current user.

        Returns:
            dict: Response containing an array of Saved Search objects with their properties.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-get

        """
        return self.get_json("/api/v1/user/searches/")

    def create(
        self,
        *,
        datasource: SavedSearchDataSource,
        query: str,
        name: str,
        description: str | None = None,
        long_description: str | None = None,
        tlp: TLPType | None = None,
        user_tags: list[str] | None = None,
        permissions: list[PermissionType] | None = None,
        **kwargs: Any,
    ) -> dict:
        """Create a Saved Search.

        Args:
            datasource (SavedSearchDataSource): Which data this Saved Search operates on
                ("hostnames" or "scans").
            query (str): Search API query string.
            name (str): User-facing short name for the saved search.
            description (str | None, optional): Short description. Defaults to None.
            long_description (str | None, optional): Long description. Defaults to None.
            tlp (TLPType | None, optional): TLP (Traffic Light Protocol) indicator for
                other users on the urlscan Pro platform. Valid values: "red", "amber+strict",
                "amber", "green", "clear". Defaults to None.
            user_tags (list[str] | None, optional): User-supplied tags to be applied to
                matching items. Apply the following prefixes to tags to define their
                visibility scope: `pro.` (urlscan Pro users), `public.` (all registered
                users), `private.` (only you), or `team.` (you and team members).
                Defaults to None.
            permissions (list[PermissionType] | None, optional): Determine whether only
                other users on the same team or everyone on urlscan Pro can see the search.
                Valid values: "public:read", "team:read", "team:write". Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Created Saved Search object containing the search properties and unique _id.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-post

        """
        search: dict[str, Any] = _compact(
            _merge(
                {
                    "datasource": datasource,
                    "query": query,
                    "name": name,
                    "description": description,
                    "longDescription": long_description,
                    "tlp": tlp,
                    "userTags": user_tags,
                    "permissions": permissions,
                },
                kwargs,
            )
        )
        data: dict[str, Any] = {"search": search}

        res = self._post("/api/v1/user/searches/", json=data)
        return self._response_to_json(res)

    def update(
        self,
        search_id: str,
        *,
        datasource: SavedSearchDataSource,
        query: str,
        name: str,
        description: str | None = None,
        long_description: str | None = None,
        tlp: TLPType | None = None,
        user_tags: list[str] | None = None,
        permissions: list[PermissionType] | None = None,
        **kwargs: Any,
    ) -> dict:
        """Update a Saved Search.

        Args:
            search_id (str): Unique ID of the saved search to update.
            datasource (SavedSearchDataSource): Which data this Saved Search operates on
                ("hostnames" or "scans").
            query (str): Search API query string.
            name (str): User-facing short name for the saved search.
            description (str | None, optional): Short description. Defaults to None.
            long_description (str | None, optional): Long description. Defaults to None.
            tlp (TLPType | None, optional): TLP (Traffic Light Protocol) indicator for
                other users on the urlscan Pro platform. Valid values: "red", "amber+strict",
                "amber", "green", "clear". Defaults to None.
            user_tags (list[str] | None, optional): User-supplied tags to be applied to
                matching items. Apply the following prefixes to tags to define their
                visibility scope: `pro.` (urlscan Pro users), `public.` (all registered
                users), `private.` (only you), or `team.` (you and team members).
                Defaults to None.
            permissions (list[PermissionType] | None, optional): Determine whether only
                other users on the same team or everyone on urlscan Pro can see the search.
                Valid values: "public:read", "team:read", "team:write". Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Updated Saved Search object containing the search properties and unique _id.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-put

        """
        search: dict[str, Any] = _compact(
            _merge(
                {
                    "datasource": datasource,
                    "query": query,
                    "name": name,
                    "description": description,
                    "longDescription": long_description,
                    "tlp": tlp,
                    "userTags": user_tags,
                    "permissions": permissions,
                },
                kwargs,
            )
        )
        data: dict[str, Any] = {"search": search}

        res = self._put(f"/api/v1/user/searches/{search_id}/", json=data)
        return self._response_to_json(res)

    def remove(self, search_id: str) -> dict:
        """Delete a Saved Search.

        Args:
            search_id (str): Unique ID of the saved search to delete.

        Returns:
            dict: Empty JSON object on success.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-delete

        """
        res = super()._delete(f"/api/v1/user/searches/{search_id}/")
        return self._response_to_json(res)

    def get_results(self, search_id: str) -> dict:
        """Get the search results for a specific Saved Search.

        Args:
            search_id (str): Unique ID of the saved search.

        Returns:
            dict: Search results matching the saved query. The structure depends on the
                datasource (hostnames or scans) specified in the saved search.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-results

        """
        return self.get_json(f"/api/v1/user/searches/{search_id}/results/")

create(*, datasource, query, name, description=None, long_description=None, tlp=None, user_tags=None, permissions=None, **kwargs)

Create a Saved Search.

Parameters:

Name Type Description Default
datasource SavedSearchDataSource

Which data this Saved Search operates on ("hostnames" or "scans").

 required
query str

Search API query string.

 required
name str

User-facing short name for the saved search.

 required
description str | None

Short description. Defaults to None.

 None
long_description str | None

Long description. Defaults to None.

 None
tlp TLPType | None

TLP (Traffic Light Protocol) indicator for other users on the urlscan Pro platform. Valid values: "red", "amber+strict", "amber", "green", "clear". Defaults to None.

 None
user_tags list[str] | None

User-supplied tags to be applied to matching items. Apply the following prefixes to tags to define their visibility scope: pro. (urlscan Pro users), public. (all registered users), private. (only you), or team. (you and team members). Defaults to None.

 None
permissions list[PermissionType] | None

Determine whether only other users on the same team or everyone on urlscan Pro can see the search. Valid values: "public:read", "team:read", "team:write". Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Created Saved Search object containing the search properties and unique _id.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-post

Source code in src/urlscan/pro/saved_search.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def create(
    self,
    *,
    datasource: SavedSearchDataSource,
    query: str,
    name: str,
    description: str | None = None,
    long_description: str | None = None,
    tlp: TLPType | None = None,
    user_tags: list[str] | None = None,
    permissions: list[PermissionType] | None = None,
    **kwargs: Any,
) -> dict:
    """Create a Saved Search.

    Args:
        datasource (SavedSearchDataSource): Which data this Saved Search operates on
            ("hostnames" or "scans").
        query (str): Search API query string.
        name (str): User-facing short name for the saved search.
        description (str | None, optional): Short description. Defaults to None.
        long_description (str | None, optional): Long description. Defaults to None.
        tlp (TLPType | None, optional): TLP (Traffic Light Protocol) indicator for
            other users on the urlscan Pro platform. Valid values: "red", "amber+strict",
            "amber", "green", "clear". Defaults to None.
        user_tags (list[str] | None, optional): User-supplied tags to be applied to
            matching items. Apply the following prefixes to tags to define their
            visibility scope: `pro.` (urlscan Pro users), `public.` (all registered
            users), `private.` (only you), or `team.` (you and team members).
            Defaults to None.
        permissions (list[PermissionType] | None, optional): Determine whether only
            other users on the same team or everyone on urlscan Pro can see the search.
            Valid values: "public:read", "team:read", "team:write". Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Created Saved Search object containing the search properties and unique _id.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-post

    """
    search: dict[str, Any] = _compact(
        _merge(
            {
                "datasource": datasource,
                "query": query,
                "name": name,
                "description": description,
                "longDescription": long_description,
                "tlp": tlp,
                "userTags": user_tags,
                "permissions": permissions,
            },
            kwargs,
        )
    )
    data: dict[str, Any] = {"search": search}

    res = self._post("/api/v1/user/searches/", json=data)
    return self._response_to_json(res)

get_list()

Get a list of Saved Searches for the current user.

Returns:

Name Type Description
dict dict

Response containing an array of Saved Search objects with their properties.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-get

Source code in src/urlscan/pro/saved_search.py 
13
14
15
16
17
18
19
20
21
22
23
def get_list(self) -> dict:
    """Get a list of Saved Searches for the current user.

    Returns:
        dict: Response containing an array of Saved Search objects with their properties.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-get

    """
    return self.get_json("/api/v1/user/searches/")

get_results(search_id)

Get the search results for a specific Saved Search.

Parameters:

Name Type Description Default
search_id str

Unique ID of the saved search.

 required

Returns:

Name Type Description
dict dict

Search results matching the saved query. The structure depends on the datasource (hostnames or scans) specified in the saved search.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-results

Source code in src/urlscan/pro/saved_search.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def get_results(self, search_id: str) -> dict:
    """Get the search results for a specific Saved Search.

    Args:
        search_id (str): Unique ID of the saved search.

    Returns:
        dict: Search results matching the saved query. The structure depends on the
            datasource (hostnames or scans) specified in the saved search.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-results

    """
    return self.get_json(f"/api/v1/user/searches/{search_id}/results/")

remove(search_id)

Delete a Saved Search.

Parameters:

Name Type Description Default
search_id str

Unique ID of the saved search to delete.

 required

Returns:

Name Type Description
dict dict

Empty JSON object on success.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-delete

Source code in src/urlscan/pro/saved_search.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def remove(self, search_id: str) -> dict:
    """Delete a Saved Search.

    Args:
        search_id (str): Unique ID of the saved search to delete.

    Returns:
        dict: Empty JSON object on success.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-delete

    """
    res = super()._delete(f"/api/v1/user/searches/{search_id}/")
    return self._response_to_json(res)

update(search_id, *, datasource, query, name, description=None, long_description=None, tlp=None, user_tags=None, permissions=None, **kwargs)

Update a Saved Search.

Parameters:

Name Type Description Default
search_id str

Unique ID of the saved search to update.

 required
datasource SavedSearchDataSource

Which data this Saved Search operates on ("hostnames" or "scans").

 required
query str

Search API query string.

 required
name str

User-facing short name for the saved search.

 required
description str | None

Short description. Defaults to None.

 None
long_description str | None

Long description. Defaults to None.

 None
tlp TLPType | None

TLP (Traffic Light Protocol) indicator for other users on the urlscan Pro platform. Valid values: "red", "amber+strict", "amber", "green", "clear". Defaults to None.

 None
user_tags list[str] | None

User-supplied tags to be applied to matching items. Apply the following prefixes to tags to define their visibility scope: pro. (urlscan Pro users), public. (all registered users), private. (only you), or team. (you and team members). Defaults to None.

 None
permissions list[PermissionType] | None

Determine whether only other users on the same team or everyone on urlscan Pro can see the search. Valid values: "public:read", "team:read", "team:write". Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Updated Saved Search object containing the search properties and unique _id.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-put

Source code in src/urlscan/pro/saved_search.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def update(
    self,
    search_id: str,
    *,
    datasource: SavedSearchDataSource,
    query: str,
    name: str,
    description: str | None = None,
    long_description: str | None = None,
    tlp: TLPType | None = None,
    user_tags: list[str] | None = None,
    permissions: list[PermissionType] | None = None,
    **kwargs: Any,
) -> dict:
    """Update a Saved Search.

    Args:
        search_id (str): Unique ID of the saved search to update.
        datasource (SavedSearchDataSource): Which data this Saved Search operates on
            ("hostnames" or "scans").
        query (str): Search API query string.
        name (str): User-facing short name for the saved search.
        description (str | None, optional): Short description. Defaults to None.
        long_description (str | None, optional): Long description. Defaults to None.
        tlp (TLPType | None, optional): TLP (Traffic Light Protocol) indicator for
            other users on the urlscan Pro platform. Valid values: "red", "amber+strict",
            "amber", "green", "clear". Defaults to None.
        user_tags (list[str] | None, optional): User-supplied tags to be applied to
            matching items. Apply the following prefixes to tags to define their
            visibility scope: `pro.` (urlscan Pro users), `public.` (all registered
            users), `private.` (only you), or `team.` (you and team members).
            Defaults to None.
        permissions (list[PermissionType] | None, optional): Determine whether only
            other users on the same team or everyone on urlscan Pro can see the search.
            Valid values: "public:read", "team:read", "team:write". Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Updated Saved Search object containing the search properties and unique _id.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches-put

    """
    search: dict[str, Any] = _compact(
        _merge(
            {
                "datasource": datasource,
                "query": query,
                "name": name,
                "description": description,
                "longDescription": long_description,
                "tlp": tlp,
                "userTags": user_tags,
                "permissions": permissions,
            },
            kwargs,
        )
    )
    data: dict[str, Any] = {"search": search}

    res = self._put(f"/api/v1/user/searches/{search_id}/", json=data)
    return self._response_to_json(res)

urlscan.pro.Subscription

Bases: BaseClient

Subscription API client.

Source code in src/urlscan/pro/subscription.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
class Subscription(BaseClient):
    """Subscription API client."""

    def get_subscriptions(self) -> dict:
        """Get a list of Subscriptions for the current user.

        Returns:
            dict: List of subscriptions.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptions

        """
        return self.get_json("/api/v1/user/subscriptions/")

    def create(
        self,
        *,
        search_ids: list[str],
        frequency: FrequencyType,
        email_addresses: list[str],
        name: str,
        is_active: bool,
        ignore_time: bool,
        description: str | None = None,
        week_days: list[WeekDaysType] | None = None,
        permissions: list[SubscriptionPermissionType] | None = None,
        channel_ids: list[str] | None = None,
        incident_channel_ids: list[str] | None = None,
        incident_profile_id: str | None = None,
        incident_visibility: IncidentVisibilityType | None = None,
        incident_creation_mode: IncidentCreationModeType | None = None,
        incident_watch_keys: IncidentWatchKeyType | None = None,
        **kwargs: Any,
    ) -> dict:
        """Create a new subscription.

        Args:
            search_ids (list[str]): Array of search IDs associated with this subscription.
            frequency (FrequencyType): Frequency of notifications ("live", "hourly", or "daily").
            email_addresses (list[str]): Email addresses receiving the notifications.
            name (str): Name of the subscription.
            is_active (bool): Whether the subscription is active.
            ignore_time (bool): Whether to ignore time constraints.
            description (str | None, optional): Description of the subscription. Defaults to None.
            week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
            permissions (list[SubscriptionPermissionType] | None, optional): Permissions associated with this subscription (team:read, team:write). Defaults to None.
            channel_ids (list[str] | None, optional): Array of channel IDs associated with this subscription. Defaults to None.
            incident_channel_ids (list[str] | None, optional): Array of incident channel IDs associated with this subscription. Defaults to None.
            incident_profile_id (str | None, optional): Incident Profile ID associated with this subscription. Defaults to None.
            incident_visibility (IncidentVisibilityType | None, optional): Incident visibility for this subscription ("unlisted" or "private"). Defaults to None.
            incident_creation_mode (IncidentCreationModeType | None, optional): Incident creation rule for this subscription ("none", "default", "always", or "ignore-if-exists"). Defaults to None.
            incident_watch_keys (IncidentWatchKeyType | None, optional): Source/key to watch in the incident (scans/page.url, scans/page.domain, scans/page.ip, scans/page.apexDomain, hostnames/hostname, hostnames/ip, hostnames/domain). Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Response containing the created subscription with an '_id' field.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionscreate

        """
        subscription: dict[str, Any] = _compact(
            _merge(
                {
                    "searchIds": search_ids,
                    "frequency": frequency,
                    "emailAddresses": email_addresses,
                    "name": name,
                    "description": description,
                    "isActive": is_active,
                    "ignoreTime": ignore_time,
                    "weekDays": week_days,
                    "permissions": permissions,
                    "channelIds": channel_ids,
                    "incidentChannelIds": incident_channel_ids,
                    "incidentProfileId": incident_profile_id,
                    "incidentVisibility": incident_visibility,
                    "incidentCreationMode": incident_creation_mode,
                    "incidentWatchKeys": incident_watch_keys,
                },
                kwargs,
            )
        )
        data = {"subscription": subscription}

        res = self._post("/api/v1/user/subscriptions/", json=data)
        return self._response_to_json(res)

    def update(
        self,
        *,
        subscription_id: str,
        search_ids: list[str],
        frequency: FrequencyType,
        email_addresses: list[str],
        name: str,
        is_active: bool,
        ignore_time: bool,
        description: str | None = None,
        week_days: list[WeekDaysType] | None = None,
        permissions: list[SubscriptionPermissionType] | None = None,
        channel_ids: list[str] | None = None,
        incident_channel_ids: list[str] | None = None,
        incident_profile_id: str | None = None,
        incident_visibility: IncidentVisibilityType | None = None,
        incident_creation_mode: IncidentCreationModeType | None = None,
        incident_watch_keys: IncidentWatchKeyType | None = None,
        **kwargs: Any,
    ) -> dict:
        """Update the settings for a subscription.

        Args:
            subscription_id (str): Subscription ID.
            search_ids (list[str]): Array of search IDs associated with this subscription.
            frequency (FrequencyType): Frequency of notifications ("live", "hourly", or "daily").
            email_addresses (list[str]): Email addresses receiving the notifications.
            name (str): Name of the subscription.
            is_active (bool): Whether the subscription is active.
            ignore_time (bool): Whether to ignore time constraints.
            description (str | None, optional): Description of the subscription. Defaults to None.
            week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
            permissions (list[SubscriptionPermissionType] | None, optional): Permissions associated with this subscription (team:read, team:write). Defaults to None.
            channel_ids (list[str] | None, optional): Array of channel IDs associated with this subscription. Defaults to None.
            incident_channel_ids (list[str] | None, optional): Array of incident channel IDs associated with this subscription. Defaults to None.
            incident_profile_id (str | None, optional): Incident Profile ID associated with this subscription. Defaults to None.
            incident_visibility (IncidentVisibilityType | None, optional): Incident visibility for this subscription ("unlisted" or "private"). Defaults to None.
            incident_creation_mode (IncidentCreationModeType | None, optional): Incident creation rule for this subscription ("none", "default", "always", or "ignore-if-exists"). Defaults to None.
            incident_watch_keys (IncidentWatchKeyType | None, optional): Source/key to watch in the incident (scans/page.url, scans/page.domain, scans/page.ip, scans/page.apexDomain, hostnames/hostname, hostnames/ip, hostnames/domain). Defaults to None.
            **kwargs: Additional parameters to include in the request payload.

        Returns:
            dict: Response containing the updated subscription with an '_id' field.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsget

        """
        subscription: dict[str, Any] = _compact(
            _merge(
                {
                    "searchIds": search_ids,
                    "frequency": frequency,
                    "emailAddresses": email_addresses,
                    "name": name,
                    "description": description,
                    "isActive": is_active,
                    "ignoreTime": ignore_time,
                    "weekDays": week_days,
                    "permissions": permissions,
                    "channelIds": channel_ids,
                    "incidentChannelIds": incident_channel_ids,
                    "incidentProfileId": incident_profile_id,
                    "incidentVisibility": incident_visibility,
                    "incidentCreationMode": incident_creation_mode,
                    "incidentWatchKeys": incident_watch_keys,
                },
                kwargs,
            )
        )
        data = {"subscription": subscription}

        res = self._put(f"/api/v1/user/subscriptions/{subscription_id}/", json=data)
        return self._response_to_json(res)

    def delete_subscription(self, *, subscription_id: str) -> dict:
        """Delete a subscription.

        Args:
            subscription_id (str): Subscription ID.

        Returns:
            dict: Empty response object confirming deletion.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsdelete

        """
        res = self._delete(f"/api/v1/user/subscriptions/{subscription_id}/")
        return self._response_to_json(res)

    def get_results(self, *, subscription_id: str, datasource: str) -> dict:
        """Get the search results for a specific subscription and datasource.

        Args:
            subscription_id (str): Subscription ID.
            datasource (str): Datasource (e.g., "scans").

        Returns:
            dict: Search results.

        Reference:
            https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsresults

        """
        return self.get_json(
            f"/api/v1/user/subscriptions/{subscription_id}/results/{datasource}/"
        )

create(*, search_ids, frequency, email_addresses, name, is_active, ignore_time, description=None, week_days=None, permissions=None, channel_ids=None, incident_channel_ids=None, incident_profile_id=None, incident_visibility=None, incident_creation_mode=None, incident_watch_keys=None, **kwargs)

Create a new subscription.

Parameters:

Name Type Description Default
search_ids list[str]

Array of search IDs associated with this subscription.

 required
frequency FrequencyType

Frequency of notifications ("live", "hourly", or "daily").

 required
email_addresses list[str]

Email addresses receiving the notifications.

 required
name str

Name of the subscription.

 required
is_active bool

Whether the subscription is active.

 required
ignore_time bool

Whether to ignore time constraints.

 required
description str | None

Description of the subscription. Defaults to None.

 None
week_days list[WeekDaysType] | None

Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.

 None
permissions list[SubscriptionPermissionType] | None

Permissions associated with this subscription (team:read, team:write). Defaults to None.

 None
channel_ids list[str] | None

Array of channel IDs associated with this subscription. Defaults to None.

 None
incident_channel_ids list[str] | None

Array of incident channel IDs associated with this subscription. Defaults to None.

 None
incident_profile_id str | None

Incident Profile ID associated with this subscription. Defaults to None.

 None
incident_visibility IncidentVisibilityType | None

Incident visibility for this subscription ("unlisted" or "private"). Defaults to None.

 None
incident_creation_mode IncidentCreationModeType | None

Incident creation rule for this subscription ("none", "default", "always", or "ignore-if-exists"). Defaults to None.

 None
incident_watch_keys IncidentWatchKeyType | None

Source/key to watch in the incident (scans/page.url, scans/page.domain, scans/page.ip, scans/page.apexDomain, hostnames/hostname, hostnames/ip, hostnames/domain). Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Response containing the created subscription with an '_id' field.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionscreate

Source code in src/urlscan/pro/subscription.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def create(
    self,
    *,
    search_ids: list[str],
    frequency: FrequencyType,
    email_addresses: list[str],
    name: str,
    is_active: bool,
    ignore_time: bool,
    description: str | None = None,
    week_days: list[WeekDaysType] | None = None,
    permissions: list[SubscriptionPermissionType] | None = None,
    channel_ids: list[str] | None = None,
    incident_channel_ids: list[str] | None = None,
    incident_profile_id: str | None = None,
    incident_visibility: IncidentVisibilityType | None = None,
    incident_creation_mode: IncidentCreationModeType | None = None,
    incident_watch_keys: IncidentWatchKeyType | None = None,
    **kwargs: Any,
) -> dict:
    """Create a new subscription.

    Args:
        search_ids (list[str]): Array of search IDs associated with this subscription.
        frequency (FrequencyType): Frequency of notifications ("live", "hourly", or "daily").
        email_addresses (list[str]): Email addresses receiving the notifications.
        name (str): Name of the subscription.
        is_active (bool): Whether the subscription is active.
        ignore_time (bool): Whether to ignore time constraints.
        description (str | None, optional): Description of the subscription. Defaults to None.
        week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
        permissions (list[SubscriptionPermissionType] | None, optional): Permissions associated with this subscription (team:read, team:write). Defaults to None.
        channel_ids (list[str] | None, optional): Array of channel IDs associated with this subscription. Defaults to None.
        incident_channel_ids (list[str] | None, optional): Array of incident channel IDs associated with this subscription. Defaults to None.
        incident_profile_id (str | None, optional): Incident Profile ID associated with this subscription. Defaults to None.
        incident_visibility (IncidentVisibilityType | None, optional): Incident visibility for this subscription ("unlisted" or "private"). Defaults to None.
        incident_creation_mode (IncidentCreationModeType | None, optional): Incident creation rule for this subscription ("none", "default", "always", or "ignore-if-exists"). Defaults to None.
        incident_watch_keys (IncidentWatchKeyType | None, optional): Source/key to watch in the incident (scans/page.url, scans/page.domain, scans/page.ip, scans/page.apexDomain, hostnames/hostname, hostnames/ip, hostnames/domain). Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Response containing the created subscription with an '_id' field.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionscreate

    """
    subscription: dict[str, Any] = _compact(
        _merge(
            {
                "searchIds": search_ids,
                "frequency": frequency,
                "emailAddresses": email_addresses,
                "name": name,
                "description": description,
                "isActive": is_active,
                "ignoreTime": ignore_time,
                "weekDays": week_days,
                "permissions": permissions,
                "channelIds": channel_ids,
                "incidentChannelIds": incident_channel_ids,
                "incidentProfileId": incident_profile_id,
                "incidentVisibility": incident_visibility,
                "incidentCreationMode": incident_creation_mode,
                "incidentWatchKeys": incident_watch_keys,
            },
            kwargs,
        )
    )
    data = {"subscription": subscription}

    res = self._post("/api/v1/user/subscriptions/", json=data)
    return self._response_to_json(res)

delete_subscription(*, subscription_id)

Delete a subscription.

Parameters:

Name Type Description Default
subscription_id str

Subscription ID.

 required

Returns:

Name Type Description
dict dict

Empty response object confirming deletion.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsdelete

Source code in src/urlscan/pro/subscription.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def delete_subscription(self, *, subscription_id: str) -> dict:
    """Delete a subscription.

    Args:
        subscription_id (str): Subscription ID.

    Returns:
        dict: Empty response object confirming deletion.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsdelete

    """
    res = self._delete(f"/api/v1/user/subscriptions/{subscription_id}/")
    return self._response_to_json(res)

get_results(*, subscription_id, datasource)

Get the search results for a specific subscription and datasource.

Parameters:

Name Type Description Default
subscription_id str

Subscription ID.

 required
datasource str

Datasource (e.g., "scans").

 required

Returns:

Name Type Description
dict dict

Search results.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsresults

Source code in src/urlscan/pro/subscription.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def get_results(self, *, subscription_id: str, datasource: str) -> dict:
    """Get the search results for a specific subscription and datasource.

    Args:
        subscription_id (str): Subscription ID.
        datasource (str): Datasource (e.g., "scans").

    Returns:
        dict: Search results.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsresults

    """
    return self.get_json(
        f"/api/v1/user/subscriptions/{subscription_id}/results/{datasource}/"
    )

get_subscriptions()

Get a list of Subscriptions for the current user.

Returns:

Name Type Description
dict dict

List of subscriptions.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptions

Source code in src/urlscan/pro/subscription.py 
20
21
22
23
24
25
26
27
28
29
30
def get_subscriptions(self) -> dict:
    """Get a list of Subscriptions for the current user.

    Returns:
        dict: List of subscriptions.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptions

    """
    return self.get_json("/api/v1/user/subscriptions/")

update(*, subscription_id, search_ids, frequency, email_addresses, name, is_active, ignore_time, description=None, week_days=None, permissions=None, channel_ids=None, incident_channel_ids=None, incident_profile_id=None, incident_visibility=None, incident_creation_mode=None, incident_watch_keys=None, **kwargs)

Update the settings for a subscription.

Parameters:

Name Type Description Default
subscription_id str

Subscription ID.

 required
search_ids list[str]

Array of search IDs associated with this subscription.

 required
frequency FrequencyType

Frequency of notifications ("live", "hourly", or "daily").

 required
email_addresses list[str]

Email addresses receiving the notifications.

 required
name str

Name of the subscription.

 required
is_active bool

Whether the subscription is active.

 required
ignore_time bool

Whether to ignore time constraints.

 required
description str | None

Description of the subscription. Defaults to None.

 None
week_days list[WeekDaysType] | None

Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.

 None
permissions list[SubscriptionPermissionType] | None

Permissions associated with this subscription (team:read, team:write). Defaults to None.

 None
channel_ids list[str] | None

Array of channel IDs associated with this subscription. Defaults to None.

 None
incident_channel_ids list[str] | None

Array of incident channel IDs associated with this subscription. Defaults to None.

 None
incident_profile_id str | None

Incident Profile ID associated with this subscription. Defaults to None.

 None
incident_visibility IncidentVisibilityType | None

Incident visibility for this subscription ("unlisted" or "private"). Defaults to None.

 None
incident_creation_mode IncidentCreationModeType | None

Incident creation rule for this subscription ("none", "default", "always", or "ignore-if-exists"). Defaults to None.

 None
incident_watch_keys IncidentWatchKeyType | None

Source/key to watch in the incident (scans/page.url, scans/page.domain, scans/page.ip, scans/page.apexDomain, hostnames/hostname, hostnames/ip, hostnames/domain). Defaults to None.

 None
**kwargs Any

Additional parameters to include in the request payload.

 {}

Returns:

Name Type Description
dict dict

Response containing the updated subscription with an '_id' field.
Reference

https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsget

Source code in src/urlscan/pro/subscription.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def update(
    self,
    *,
    subscription_id: str,
    search_ids: list[str],
    frequency: FrequencyType,
    email_addresses: list[str],
    name: str,
    is_active: bool,
    ignore_time: bool,
    description: str | None = None,
    week_days: list[WeekDaysType] | None = None,
    permissions: list[SubscriptionPermissionType] | None = None,
    channel_ids: list[str] | None = None,
    incident_channel_ids: list[str] | None = None,
    incident_profile_id: str | None = None,
    incident_visibility: IncidentVisibilityType | None = None,
    incident_creation_mode: IncidentCreationModeType | None = None,
    incident_watch_keys: IncidentWatchKeyType | None = None,
    **kwargs: Any,
) -> dict:
    """Update the settings for a subscription.

    Args:
        subscription_id (str): Subscription ID.
        search_ids (list[str]): Array of search IDs associated with this subscription.
        frequency (FrequencyType): Frequency of notifications ("live", "hourly", or "daily").
        email_addresses (list[str]): Email addresses receiving the notifications.
        name (str): Name of the subscription.
        is_active (bool): Whether the subscription is active.
        ignore_time (bool): Whether to ignore time constraints.
        description (str | None, optional): Description of the subscription. Defaults to None.
        week_days (list[WeekDaysType] | None, optional): Days of the week alerts will be generated (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday). Defaults to None.
        permissions (list[SubscriptionPermissionType] | None, optional): Permissions associated with this subscription (team:read, team:write). Defaults to None.
        channel_ids (list[str] | None, optional): Array of channel IDs associated with this subscription. Defaults to None.
        incident_channel_ids (list[str] | None, optional): Array of incident channel IDs associated with this subscription. Defaults to None.
        incident_profile_id (str | None, optional): Incident Profile ID associated with this subscription. Defaults to None.
        incident_visibility (IncidentVisibilityType | None, optional): Incident visibility for this subscription ("unlisted" or "private"). Defaults to None.
        incident_creation_mode (IncidentCreationModeType | None, optional): Incident creation rule for this subscription ("none", "default", "always", or "ignore-if-exists"). Defaults to None.
        incident_watch_keys (IncidentWatchKeyType | None, optional): Source/key to watch in the incident (scans/page.url, scans/page.domain, scans/page.ip, scans/page.apexDomain, hostnames/hostname, hostnames/ip, hostnames/domain). Defaults to None.
        **kwargs: Additional parameters to include in the request payload.

    Returns:
        dict: Response containing the updated subscription with an '_id' field.

    Reference:
        https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsget

    """
    subscription: dict[str, Any] = _compact(
        _merge(
            {
                "searchIds": search_ids,
                "frequency": frequency,
                "emailAddresses": email_addresses,
                "name": name,
                "description": description,
                "isActive": is_active,
                "ignoreTime": ignore_time,
                "weekDays": week_days,
                "permissions": permissions,
                "channelIds": channel_ids,
                "incidentChannelIds": incident_channel_ids,
                "incidentProfileId": incident_profile_id,
                "incidentVisibility": incident_visibility,
                "incidentCreationMode": incident_creation_mode,
                "incidentWatchKeys": incident_watch_keys,
            },
            kwargs,
        )
    )
    data = {"subscription": subscription}

    res = self._put(f"/api/v1/user/subscriptions/{subscription_id}/", json=data)
    return self._response_to_json(res)