Coverage for fingerprint_server_sdk/api/fingerprint_api.py: 84%

1""" 

2Server API 

3Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. 

4Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. 

5The API also supports collection of Automation Intelligence for requests to your server in edge, pre-origin, or middleware contexts. 

6 

7The version of the OpenAPI document: 4 

8Contact: support@fingerprint.com 

9Generated by OpenAPI Generator (https://openapi-generator.tech) 

10 

11Do not edit the class manually. 

12""" # noqa: E501 

13 

14from datetime import date, datetime 

15from typing import Annotated, Any, Optional, Union # noqa: UP035 

16 

17from pydantic import Field, StrictBool, StrictFloat, StrictInt, StrictStr, validate_call 

18 

19from fingerprint_server_sdk.api_client import ApiClient, RequestSerialized 

20from fingerprint_server_sdk.api_response import ApiResponse 

21from fingerprint_server_sdk.configuration import Configuration 

22from fingerprint_server_sdk.models.bot_info_category import BotInfoCategory 

23from fingerprint_server_sdk.models.bot_info_confidence import BotInfoConfidence 

24from fingerprint_server_sdk.models.bot_info_identity import BotInfoIdentity 

25from fingerprint_server_sdk.models.event import Event 

26from fingerprint_server_sdk.models.event_search import EventSearch 

27from fingerprint_server_sdk.models.event_update import EventUpdate 

28from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot 

29from fingerprint_server_sdk.models.search_events_bot_info import SearchEventsBotInfo 

30from fingerprint_server_sdk.models.search_events_end_parameter import SearchEventsEndParameter 

31from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( 

32 SearchEventsIncrementalIdentificationStatus, 

33) 

34from fingerprint_server_sdk.models.search_events_rare_device_percentile_bucket import ( 

35 SearchEventsRareDevicePercentileBucket, 

36) 

37from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform 

38from fingerprint_server_sdk.models.search_events_source import SearchEventsSource 

39from fingerprint_server_sdk.models.search_events_start_parameter import SearchEventsStartParameter 

40from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence 

41from fingerprint_server_sdk.rest import RESTResponseType 

42 

43# Type alias for query and form parameter values 

44ParamValue = Union[ 

45 list[BotInfoCategory], 

46 list[BotInfoIdentity], 

47 list[BotInfoConfidence], 

48 list[SearchEventsSource], 

49 str, 

50 int, 

51 float, 

52 bool, 

53 list[str], 

54] 

55 

56 

57class FingerprintApi: 

58 """Fingerprint Python Server SDK 

59 

60 Fingerprint (https://fingerprint.com) is a device intelligence platform offering industry-leading accuracy. Fingerprint Server API allows you to search, update, and delete identification events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. 

61 

62 :param configuration: API client configuration. 

63 """ 

64 

65 def __init__(self, configuration: Configuration) -> None: 

66 self.api_client = ApiClient(configuration) 

67 

68 @validate_call 

69 def delete_visitor_data( 

70 self, 

71 visitor_id: Annotated[ 

72 StrictStr, 

73 Field( 

74 description='The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete.' 

75 ), 

76 ], 

77 _request_timeout: Union[ 

78 None, 

79 Annotated[StrictFloat, Field(gt=0)], 

80 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

81 ] = None, 

82 _request_auth: Optional[dict[StrictStr, Any]] = None, 

83 _content_type: Optional[StrictStr] = None, 

84 _headers: Optional[dict[StrictStr, Any]] = None, 

85 ) -> None: 

86 """Delete a visitor ID 

87 

88 Use this API to request the deletion of all data associated with a specific visitor ID. Upon a request to delete data for a visitor ID, - The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. - The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. - The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). The following timeline illustrates which events are deleted and which remain after a DELETE API request: ``` Day 1: First visit from browser A. (Assigned visitor ID: VID1000) Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 14: Delete VID1000 Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) ``` ### Availability This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). ### Rate limits and daily quota The rate limits and daily quota for this API **differ** from those for our other API. The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). 

89 

90 :param visitor_id: The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. (required) 

91 :type visitor_id: str 

92 :param _request_timeout: timeout setting for this request. If one 

93 number provided, it will be total request 

94 timeout. It can also be a pair (tuple) of 

95 (connection, read) timeouts. 

96 :type _request_timeout: int, tuple(int, int), optional 

97 :param _request_auth: set to override the auth_settings for an a single 

98 request; this effectively ignores the 

99 authentication in the spec for a single request. 

100 :type _request_auth: dict, optional 

101 :param _content_type: force content-type for the request. 

102 :type _content_type: str, Optional 

103 :param _headers: set to override the headers for a single 

104 request; this effectively ignores the headers 

105 in the spec for a single request. 

106 :type _headers: dict, optional 

107 :return: Returns the result object. 

108 """ # noqa: E501 

109 

110 _param = self._delete_visitor_data_serialize( 

111 visitor_id=visitor_id, 

112 _request_auth=_request_auth, 

113 _content_type=_content_type, 

114 _headers=_headers, 

115 ) 

116 

117 _response_types_map: dict[str, Optional[str]] = { 

118 '200': None, 

119 '400': 'ErrorResponse', 

120 '403': 'ErrorResponse', 

121 '404': 'ErrorResponse', 

122 '429': 'ErrorResponse', 

123 } 

124 

125 response_data = self.api_client.call_api(*_param, _request_timeout=_request_timeout) 

126 response_data.read() 

127 self.api_client.response_deserialize( 

128 response_data=response_data, 

129 response_types_map=_response_types_map, 

130 ) 

131 

132 @validate_call 

133 def delete_visitor_data_with_http_info( 

134 self, 

135 visitor_id: Annotated[ 

136 StrictStr, 

137 Field( 

138 description='The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete.' 

139 ), 

140 ], 

141 _request_timeout: Union[ 

142 None, 

143 Annotated[StrictFloat, Field(gt=0)], 

144 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

145 ] = None, 

146 _request_auth: Optional[dict[StrictStr, Any]] = None, 

147 _content_type: Optional[StrictStr] = None, 

148 _headers: Optional[dict[StrictStr, Any]] = None, 

149 ) -> ApiResponse[None]: 

150 """Delete a visitor ID 

151 

152 Use this API to request the deletion of all data associated with a specific visitor ID. Upon a request to delete data for a visitor ID, - The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. - The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. - The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). The following timeline illustrates which events are deleted and which remain after a DELETE API request: ``` Day 1: First visit from browser A. (Assigned visitor ID: VID1000) Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 14: Delete VID1000 Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) ``` ### Availability This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). ### Rate limits and daily quota The rate limits and daily quota for this API **differ** from those for our other API. The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). 

153 

154 :param visitor_id: The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. (required) 

155 :type visitor_id: str 

156 :param _request_timeout: timeout setting for this request. If one 

157 number provided, it will be total request 

158 timeout. It can also be a pair (tuple) of 

159 (connection, read) timeouts. 

160 :type _request_timeout: int, tuple(int, int), optional 

161 :param _request_auth: set to override the auth_settings for an a single 

162 request; this effectively ignores the 

163 authentication in the spec for a single request. 

164 :type _request_auth: dict, optional 

165 :param _content_type: force content-type for the request. 

166 :type _content_type: str, Optional 

167 :param _headers: set to override the headers for a single 

168 request; this effectively ignores the headers 

169 in the spec for a single request. 

170 :type _headers: dict, optional 

171 :return: Returns the result object. 

172 """ # noqa: E501 

173 

174 _param = self._delete_visitor_data_serialize( 

175 visitor_id=visitor_id, 

176 _request_auth=_request_auth, 

177 _content_type=_content_type, 

178 _headers=_headers, 

179 ) 

180 

181 _response_types_map: dict[str, Optional[str]] = { 

182 '200': None, 

183 '400': 'ErrorResponse', 

184 '403': 'ErrorResponse', 

185 '404': 'ErrorResponse', 

186 '429': 'ErrorResponse', 

187 } 

188 

189 response_data = self.api_client.call_api(*_param, _request_timeout=_request_timeout) 

190 response_data.read() 

191 return self.api_client.response_deserialize( 

192 response_data=response_data, 

193 response_types_map=_response_types_map, 

194 ) 

195 

196 @validate_call 

197 def delete_visitor_data_without_preload_content( 

198 self, 

199 visitor_id: Annotated[ 

200 StrictStr, 

201 Field( 

202 description='The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete.' 

203 ), 

204 ], 

205 _request_timeout: Union[ 

206 None, 

207 Annotated[StrictFloat, Field(gt=0)], 

208 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

209 ] = None, 

210 _request_auth: Optional[dict[StrictStr, Any]] = None, 

211 _content_type: Optional[StrictStr] = None, 

212 _headers: Optional[dict[StrictStr, Any]] = None, 

213 ) -> RESTResponseType: 

214 """Delete a visitor ID 

215 

216 Use this API to request the deletion of all data associated with a specific visitor ID. Upon a request to delete data for a visitor ID, - The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. - The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. - The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). The following timeline illustrates which events are deleted and which remain after a DELETE API request: ``` Day 1: First visit from browser A. (Assigned visitor ID: VID1000) Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 14: Delete VID1000 Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) ``` ### Availability This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). ### Rate limits and daily quota The rate limits and daily quota for this API **differ** from those for our other API. The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). 

217 

218 :param visitor_id: The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. (required) 

219 :type visitor_id: str 

220 :param _request_timeout: timeout setting for this request. If one 

221 number provided, it will be total request 

222 timeout. It can also be a pair (tuple) of 

223 (connection, read) timeouts. 

224 :type _request_timeout: int, tuple(int, int), optional 

225 :param _request_auth: set to override the auth_settings for an a single 

226 request; this effectively ignores the 

227 authentication in the spec for a single request. 

228 :type _request_auth: dict, optional 

229 :param _content_type: force content-type for the request. 

230 :type _content_type: str, Optional 

231 :param _headers: set to override the headers for a single 

232 request; this effectively ignores the headers 

233 in the spec for a single request. 

234 :type _headers: dict, optional 

235 :return: Returns the result object. 

236 """ # noqa: E501 

237 

238 _param = self._delete_visitor_data_serialize( 

239 visitor_id=visitor_id, 

240 _request_auth=_request_auth, 

241 _content_type=_content_type, 

242 _headers=_headers, 

243 ) 

244 

245 _response_types_map: dict[str, Optional[str]] = { 

246 '200': None, 

247 '400': 'ErrorResponse', 

248 '403': 'ErrorResponse', 

249 '404': 'ErrorResponse', 

250 '429': 'ErrorResponse', 

251 } 

252 

253 response_data = self.api_client.call_api(*_param, _request_timeout=_request_timeout) 

254 return response_data.response 

255 

256 def _delete_visitor_data_serialize( 

257 self, 

258 visitor_id: str, 

259 _request_auth: Optional[dict[StrictStr, Any]], 

260 _content_type: Optional[StrictStr], 

261 _headers: Optional[dict[StrictStr, Any]], 

262 ) -> RequestSerialized: 

263 

264 _collection_formats: dict[str, str] = {} 

265 

266 _path_params: dict[str, str] = {} 

267 _query_params: list[tuple[str, ParamValue]] = [] 

268 _header_params: dict[str, Optional[str]] = _headers or {} 

269 _form_params: list[tuple[str, ParamValue]] = [] 

270 _files: dict[ 

271 str, 

272 Union[str, bytes, list[str], list[bytes], tuple[str, bytes], list[tuple[str, bytes]]], 

273 ] = {} 

274 _body_params: Optional[Any] = None 

275 

276 # process the path parameters 

277 if visitor_id is not None: 

278 _path_params['visitor_id'] = visitor_id 

279 

280 # set the HTTP header `Accept` 

281 if 'Accept' not in _header_params: 

282 _header_params['Accept'] = self.api_client.select_header_accept(['application/json']) 

283 

284 # authentication setting 

285 _auth_settings: list[str] = ['bearerAuth'] 

286 

287 return self.api_client.param_serialize( 

288 method='DELETE', 

289 resource_path='/visitors/{visitor_id}', 

290 path_params=_path_params, 

291 query_params=_query_params, 

292 header_params=_header_params, 

293 body=_body_params, 

294 post_params=_form_params, 

295 files=_files, 

296 auth_settings=_auth_settings, 

297 collection_formats=_collection_formats, 

298 _request_auth=_request_auth, 

299 ) 

300 

301 @validate_call 

302 def get_event( 

303 self, 

304 event_id: Annotated[ 

305 StrictStr, 

306 Field( 

307 description='The unique [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of each identification request (`requestId` can be used in its place).' 

308 ), 

309 ], 

310 ruleset_id: Annotated[ 

311 Optional[StrictStr], 

312 Field( 

313 description='The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response. ' 

314 ), 

315 ] = None, 

316 _request_timeout: Union[ 

317 None, 

318 Annotated[StrictFloat, Field(gt=0)], 

319 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

320 ] = None, 

321 _request_auth: Optional[dict[StrictStr, Any]] = None, 

322 _content_type: Optional[StrictStr] = None, 

323 _headers: Optional[dict[StrictStr, Any]] = None, 

324 ) -> Event: 

325 """Get an event by event ID 

326 

327 Get a detailed analysis of an individual identification event, including Smart Signals. Use `event_id` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `event_id`. 

328 

329 :param event_id: The unique [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of each identification request (`requestId` can be used in its place). (required) 

330 :type event_id: str 

331 :param ruleset_id: The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response. 

332 :type ruleset_id: str 

333 :param _request_timeout: timeout setting for this request. If one 

334 number provided, it will be total request 

335 timeout. It can also be a pair (tuple) of 

336 (connection, read) timeouts. 

337 :type _request_timeout: int, tuple(int, int), optional 

338 :param _request_auth: set to override the auth_settings for an a single 

339 request; this effectively ignores the 

340 authentication in the spec for a single request. 

341 :type _request_auth: dict, optional 

342 :param _content_type: force content-type for the request. 

343 :type _content_type: str, Optional 

344 :param _headers: set to override the headers for a single 

345 request; this effectively ignores the headers 

346 in the spec for a single request. 

347 :type _headers: dict, optional 

348 :return: Returns the result object. 

349 """ # noqa: E501 

350 

351 _param = self._get_event_serialize( 

352 event_id=event_id, 

353 ruleset_id=ruleset_id, 

354 _request_auth=_request_auth, 

355 _content_type=_content_type, 

356 _headers=_headers, 

357 ) 

358 

359 _response_types_map: dict[str, Optional[str]] = { 

360 '200': 'Event', 

361 '400': 'ErrorResponse', 

362 '403': 'ErrorResponse', 

363 '404': 'ErrorResponse', 

364 '429': 'ErrorResponse', 

365 '500': 'ErrorResponse', 

366 } 

367 

368 response_data = self.api_client.call_api(*_param, _request_timeout=_request_timeout) 

369 response_data.read() 

370 return self.api_client.response_deserialize( 

371 response_data=response_data, 

372 response_types_map=_response_types_map, 

373 ).data 

374 

375 @validate_call 

376 def get_event_with_http_info( 

377 self, 

378 event_id: Annotated[ 

379 StrictStr, 

380 Field( 

381 description='The unique [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of each identification request (`requestId` can be used in its place).' 

382 ), 

383 ], 

384 ruleset_id: Annotated[ 

385 Optional[StrictStr], 

386 Field( 

387 description='The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response. ' 

388 ), 

389 ] = None, 

390 _request_timeout: Union[ 

391 None, 

392 Annotated[StrictFloat, Field(gt=0)], 

393 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

394 ] = None, 

395 _request_auth: Optional[dict[StrictStr, Any]] = None, 

396 _content_type: Optional[StrictStr] = None, 

397 _headers: Optional[dict[StrictStr, Any]] = None, 

398 ) -> ApiResponse[Event]: 

399 """Get an event by event ID 

400 

401 Get a detailed analysis of an individual identification event, including Smart Signals. Use `event_id` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `event_id`. 

402 

403 :param event_id: The unique [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of each identification request (`requestId` can be used in its place). (required) 

404 :type event_id: str 

405 :param ruleset_id: The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response. 

406 :type ruleset_id: str 

407 :param _request_timeout: timeout setting for this request. If one 

408 number provided, it will be total request 

409 timeout. It can also be a pair (tuple) of 

410 (connection, read) timeouts. 

411 :type _request_timeout: int, tuple(int, int), optional 

412 :param _request_auth: set to override the auth_settings for an a single 

413 request; this effectively ignores the 

414 authentication in the spec for a single request. 

415 :type _request_auth: dict, optional 

416 :param _content_type: force content-type for the request. 

417 :type _content_type: str, Optional 

418 :param _headers: set to override the headers for a single 

419 request; this effectively ignores the headers 

420 in the spec for a single request. 

421 :type _headers: dict, optional 

422 :return: Returns the result object. 

423 """ # noqa: E501 

424 

425 _param = self._get_event_serialize( 

426 event_id=event_id, 

427 ruleset_id=ruleset_id, 

428 _request_auth=_request_auth, 

429 _content_type=_content_type, 

430 _headers=_headers, 

431 ) 

432 

433 _response_types_map: dict[str, Optional[str]] = { 

434 '200': 'Event', 

435 '400': 'ErrorResponse', 

436 '403': 'ErrorResponse', 

437 '404': 'ErrorResponse', 

438 '429': 'ErrorResponse', 

439 '500': 'ErrorResponse', 

440 } 

441 

442 response_data = self.api_client.call_api(*_param, _request_timeout=_request_timeout) 

443 response_data.read() 

444 return self.api_client.response_deserialize( 

445 response_data=response_data, 

446 response_types_map=_response_types_map, 

447 ) 

448 

449 @validate_call 

450 def get_event_without_preload_content( 

451 self, 

452 event_id: Annotated[ 

453 StrictStr, 

454 Field( 

455 description='The unique [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of each identification request (`requestId` can be used in its place).' 

456 ), 

457 ], 

458 ruleset_id: Annotated[ 

459 Optional[StrictStr], 

460 Field( 

461 description='The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response. ' 

462 ), 

463 ] = None, 

464 _request_timeout: Union[ 

465 None, 

466 Annotated[StrictFloat, Field(gt=0)], 

467 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

468 ] = None, 

469 _request_auth: Optional[dict[StrictStr, Any]] = None, 

470 _content_type: Optional[StrictStr] = None, 

471 _headers: Optional[dict[StrictStr, Any]] = None, 

472 ) -> RESTResponseType: 

473 """Get an event by event ID 

474 

475 Get a detailed analysis of an individual identification event, including Smart Signals. Use `event_id` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `event_id`. 

476 

477 :param event_id: The unique [identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of each identification request (`requestId` can be used in its place). (required) 

478 :type event_id: str 

479 :param ruleset_id: The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response. 

480 :type ruleset_id: str 

481 :param _request_timeout: timeout setting for this request. If one 

482 number provided, it will be total request 

483 timeout. It can also be a pair (tuple) of 

484 (connection, read) timeouts. 

485 :type _request_timeout: int, tuple(int, int), optional 

486 :param _request_auth: set to override the auth_settings for an a single 

487 request; this effectively ignores the 

488 authentication in the spec for a single request. 

489 :type _request_auth: dict, optional 

490 :param _content_type: force content-type for the request. 

491 :type _content_type: str, Optional 

492 :param _headers: set to override the headers for a single 

493 request; this effectively ignores the headers 

494 in the spec for a single request. 

495 :type _headers: dict, optional 

496 :return: Returns the result object. 

497 """ # noqa: E501 

498 

499 _param = self._get_event_serialize( 

500 event_id=event_id, 

501 ruleset_id=ruleset_id, 

502 _request_auth=_request_auth, 

503 _content_type=_content_type, 

504 _headers=_headers, 

505 ) 

506 

507 _response_types_map: dict[str, Optional[str]] = { 

508 '200': 'Event', 

509 '400': 'ErrorResponse', 

510 '403': 'ErrorResponse', 

511 '404': 'ErrorResponse', 

512 '429': 'ErrorResponse', 

513 '500': 'ErrorResponse', 

514 } 

515 

516 response_data = self.api_client.call_api(*_param, _request_timeout=_request_timeout) 

517 return response_data.response 

518 

519 def _get_event_serialize( 

520 self, 

521 event_id: str, 

522 ruleset_id: Optional[str], 

523 _request_auth: Optional[dict[StrictStr, Any]], 

524 _content_type: Optional[StrictStr], 

525 _headers: Optional[dict[StrictStr, Any]], 

526 ) -> RequestSerialized: 

527 

528 _collection_formats: dict[str, str] = {} 

529 

530 _path_params: dict[str, str] = {} 

531 _query_params: list[tuple[str, ParamValue]] = [] 

532 _header_params: dict[str, Optional[str]] = _headers or {} 

533 _form_params: list[tuple[str, ParamValue]] = [] 

534 _files: dict[ 

535 str, 

536 Union[str, bytes, list[str], list[bytes], tuple[str, bytes], list[tuple[str, bytes]]], 

537 ] = {} 

538 _body_params: Optional[Any] = None 

539 

540 # process the path parameters 

541 if event_id is not None: 

542 _path_params['event_id'] = event_id 

543 

544 # process the query parameters 

545 if ruleset_id is not None: 

546 _query_params.append(('ruleset_id', ruleset_id)) 

547 

548 # set the HTTP header `Accept` 

549 if 'Accept' not in _header_params: 

550 _header_params['Accept'] = self.api_client.select_header_accept(['application/json']) 

551 

552 # authentication setting 

553 _auth_settings: list[str] = ['bearerAuth'] 

554 

555 return self.api_client.param_serialize( 

556 method='GET', 

557 resource_path='/events/{event_id}', 

558 path_params=_path_params, 

559 query_params=_query_params, 

560 header_params=_header_params, 

561 body=_body_params, 

562 post_params=_form_params, 

563 files=_files, 

564 auth_settings=_auth_settings, 

565 collection_formats=_collection_formats, 

566 _request_auth=_request_auth, 

567 ) 

568 

569 @validate_call 

570 def search_events( 

571 self, 

572 limit: Annotated[ 

573 Optional[Annotated[int, Field(le=100, strict=True, ge=1)]], 

574 Field( 

575 description='Maximum number of events to return. Defaults to 10 when omitted. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. ' 

576 ), 

577 ] = None, 

578 pagination_key: Annotated[ 

579 Optional[StrictStr], 

580 Field( 

581 description='Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 100 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=S9rgMMUb4z3X5t5pr_tSgoSZlmyF0O8X7kCV2m981-iY1LmRTjraa1rTk3L-hQExnDWCi0RA-zAIjaVSTNO2AN2eqQWgzT0RjbieMxRfSdkM-HmOhdOgdQvYfPG3vqU1DJKh4Q` ' 

582 ), 

583 ] = None, 

584 visitor_id: Annotated[ 

585 Optional[StrictStr], 

586 Field( 

587 description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). ' 

588 ), 

589 ] = None, 

590 high_recall_id: Annotated[ 

591 Optional[StrictStr], 

592 Field( 

593 description='The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). ' 

594 ), 

595 ] = None, 

596 bot: Annotated[ 

597 Optional[SearchEventsBot], 

598 Field( 

599 description='Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. ' 

600 ), 

601 ] = None, 

602 bot_info: Annotated[ 

603 Optional[SearchEventsBotInfo], 

604 Field( 

605 description='Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. ' 

606 ), 

607 ] = None, 

608 bot_info_category: Annotated[ 

609 Optional[list[BotInfoCategory]], 

610 Field( 

611 description='Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. ' 

612 ), 

613 ] = None, 

614 bot_info_identity: Annotated[ 

615 Optional[list[BotInfoIdentity]], 

616 Field( 

617 description='Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. ' 

618 ), 

619 ] = None, 

620 bot_info_confidence: Annotated[ 

621 Optional[list[BotInfoConfidence]], 

622 Field( 

623 description='Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. ' 

624 ), 

625 ] = None, 

626 bot_info_provider: Annotated[ 

627 Optional[list[StrictStr]], 

628 Field( 

629 description='Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. ' 

630 ), 

631 ] = None, 

632 bot_info_name: Annotated[ 

633 Optional[list[StrictStr]], 

634 Field( 

635 description='Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. ' 

636 ), 

637 ] = None, 

638 ip_address: Annotated[ 

639 Optional[StrictStr], 

640 Field( 

641 description='Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 ' 

642 ), 

643 ] = None, 

644 asn: Annotated[ 

645 Optional[StrictStr], 

646 Field( 

647 description="Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. " 

648 ), 

649 ] = None, 

650 linked_id: Annotated[ 

651 Optional[StrictStr], 

652 Field( 

653 description='Filter events by your custom identifier. You can use [linked Ids](https://docs.fingerprint.com/reference/js-agent-v4-get-function#linkedid) to associate identification requests with your own identifier, for example, session Id, purchase Id, or transaction Id. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. ' 

654 ), 

655 ] = None, 

656 url: Annotated[ 

657 Optional[StrictStr], 

658 Field( 

659 description='Filter events by the URL (`url` property) associated with the event. ' 

660 ), 

661 ] = None, 

662 bundle_id: Annotated[ 

663 Optional[StrictStr], 

664 Field(description='Filter events by the Bundle ID (iOS) associated with the event. '), 

665 ] = None, 

666 package_name: Annotated[ 

667 Optional[StrictStr], 

668 Field( 

669 description='Filter events by the Package Name (Android) associated with the event. ' 

670 ), 

671 ] = None, 

672 origin: Annotated[ 

673 Optional[StrictStr], 

674 Field( 

675 description='Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com) ' 

676 ), 

677 ] = None, 

678 start: Annotated[ 

679 Optional[SearchEventsStartParameter], 

680 Field( 

681 description="Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. ", 

682 ), 

683 ] = None, 

684 end: Annotated[ 

685 Optional[SearchEventsEndParameter], 

686 Field( 

687 description="Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. ", 

688 ), 

689 ] = None, 

690 reverse: Annotated[ 

691 Optional[StrictBool], 

692 Field( 

693 description='When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order). ' 

694 ), 

695 ] = None, 

696 suspect: Annotated[ 

697 Optional[StrictBool], 

698 Field( 

699 description='Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response. ' 

700 ), 

701 ] = None, 

702 vpn: Annotated[ 

703 Optional[StrictBool], 

704 Field( 

705 description='Filter events by VPN Detection result. > Note: When using this parameter, only events with the `vpn` property set to `true` or `false` are returned. Events without a `vpn` Smart Signal result are left out of the response. ' 

706 ), 

707 ] = None, 

708 virtual_machine: Annotated[ 

709 Optional[StrictBool], 

710 Field( 

711 description='Filter events by Virtual Machine Detection result. > Note: When using this parameter, only events with the `virtual_machine` property set to `true` or `false` are returned. Events without a `virtual_machine` Smart Signal result are left out of the response. ' 

712 ), 

713 ] = None, 

714 tampering: Annotated[ 

715 Optional[StrictBool], 

716 Field( 

717 description='Filter events by Browser Tampering Detection result. > Note: When using this parameter, only events with the `tampering.result` property set to `true` or `false` are returned. Events without a `tampering` Smart Signal result are left out of the response. ' 

718 ), 

719 ] = None, 

720 anti_detect_browser: Annotated[ 

721 Optional[StrictBool], 

722 Field( 

723 description='Filter events by Anti-detect Browser Detection result. > Note: When using this parameter, only events with the `tampering.anti_detect_browser` property set to `true` or `false` are returned. Events without a `tampering` Smart Signal result are left out of the response. ' 

724 ), 

725 ] = None, 

726 incognito: Annotated[ 

727 Optional[StrictBool], 

728 Field( 

729 description='Filter events by Browser Incognito Detection result. > Note: When using this parameter, only events with the `incognito` property set to `true` or `false` are returned. Events without an `incognito` Smart Signal result are left out of the response. ' 

730 ), 

731 ] = None, 

732 privacy_settings: Annotated[ 

733 Optional[StrictBool], 

734 Field( 

735 description='Filter events by Privacy Settings Detection result. > Note: When using this parameter, only events with the `privacy_settings` property set to `true` or `false` are returned. Events without a `privacy_settings` Smart Signal result are left out of the response. ' 

736 ), 

737 ] = None, 

738 jailbroken: Annotated[ 

739 Optional[StrictBool], 

740 Field( 

741 description='Filter events by Jailbroken Device Detection result. > Note: When using this parameter, only events with the `jailbroken` property set to `true` or `false` are returned. Events without a `jailbroken` Smart Signal result are left out of the response. ' 

742 ), 

743 ] = None, 

744 frida: Annotated[ 

745 Optional[StrictBool], 

746 Field( 

747 description='Filter events by Frida Detection result. > Note: When using this parameter, only events with the `frida` property set to `true` or `false` are returned. Events without a `frida` Smart Signal result are left out of the response. ' 

748 ), 

749 ] = None, 

750 factory_reset: Annotated[ 

751 Optional[StrictBool], 

752 Field( 

753 description='Filter events by Factory Reset Detection result. > Note: When using this parameter, only events with a `factory_reset` time. Events without a `factory_reset` Smart Signal result are left out of the response. ' 

754 ), 

755 ] = None, 

756 cloned_app: Annotated[ 

757 Optional[StrictBool], 

758 Field( 

759 description='Filter events by Cloned App Detection result. > Note: When using this parameter, only events with the `cloned_app` property set to `true` or `false` are returned. Events without a `cloned_app` Smart Signal result are left out of the response. ' 

760 ), 

761 ] = None, 

762 emulator: Annotated[ 

763 Optional[StrictBool], 

764 Field( 

765 description='Filter events by Android Emulator Detection result. > Note: When using this parameter, only events with the `emulator` property set to `true` or `false` are returned. Events without an `emulator` Smart Signal result are left out of the response. ' 

766 ), 

767 ] = None, 

768 root_apps: Annotated[ 

769 Optional[StrictBool], 

770 Field( 

771 description='Filter events by Rooted Device Detection result. > Note: When using this parameter, only events with the `root_apps` property set to `true` or `false` are returned. Events without a `root_apps` Smart Signal result are left out of the response. ' 

772 ), 

773 ] = None, 

774 vpn_confidence: Annotated[ 

775 Optional[SearchEventsVpnConfidence], 

776 Field( 

777 description='Filter events by VPN Detection result confidence level. `high` - events with high VPN Detection confidence. `medium` - events with medium VPN Detection confidence. `low` - events with low VPN Detection confidence. > Note: When using this parameter, only events with the `vpn.confidence` property set to a valid value are returned. Events without a `vpn` Smart Signal result are left out of the response. ' 

778 ), 

779 ] = None, 

780 min_suspect_score: Annotated[ 

781 Optional[Union[StrictFloat, StrictInt]], 

782 Field( 

783 description='Filter events with Suspect Score result above a provided minimum threshold. > Note: When using this parameter, only events where the `suspect_score` property set to a value exceeding your threshold are returned. Events without a `suspect_score` Smart Signal result are left out of the response. ' 

784 ), 

785 ] = None, 

786 developer_tools: Annotated[ 

787 Optional[StrictBool], 

788 Field( 

789 description='Filter events by Developer Tools detection result. > Note: When using this parameter, only events with the `developer_tools` property set to `true` or `false` are returned. Events without a `developer_tools` Smart Signal result are left out of the response. ' 

790 ), 

791 ] = None, 

792 location_spoofing: Annotated[ 

793 Optional[StrictBool], 

794 Field( 

795 description='Filter events by Location Spoofing detection result. > Note: When using this parameter, only events with the `location_spoofing` property set to `true` or `false` are returned. Events without a `location_spoofing` Smart Signal result are left out of the response. ' 

796 ), 

797 ] = None, 

798 mitm_attack: Annotated[ 

799 Optional[StrictBool], 

800 Field( 

801 description='Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. ' 

802 ), 

803 ] = None, 

804 rare_device: Annotated[ 

805 Optional[StrictBool], 

806 Field( 

807 description='Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). ' 

808 ), 

809 ] = None, 

810 rare_device_percentile_bucket: Annotated[ 

811 Optional[SearchEventsRareDevicePercentileBucket], 

812 Field( 

813 description='Filter events by Device Rarity percentile bucket. `<p95` - device configuration is in the bottom 95% (most common). `p95-p99` - device is in the 95th to 99th percentile. `p99-p99.5` - device is in the 99th to 99.5th percentile. `p99.5-p99.9` - device is in the 99.5th to 99.9th percentile. `p99.9+` - device is in the top 0.1% (rarest). `not_seen` - device configuration has never been observed before. > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). ' 

814 ), 

815 ] = None, 

816 proxy: Annotated[ 

817 Optional[StrictBool], 

818 Field( 

819 description='Filter events by Proxy detection result. > Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. ' 

820 ), 

821 ] = None, 

822 sdk_version: Annotated[ 

823 Optional[StrictStr], 

824 Field( 

825 description='Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` ' 

826 ), 

827 ] = None, 

828 sdk_platform: Annotated[ 

829 Optional[SearchEventsSdkPlatform], 

830 Field( 

831 description='Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. ' 

832 ), 

833 ] = None, 

834 environment: Annotated[ 

835 Optional[list[StrictStr]], 

836 Field( 

837 description='Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. ' 

838 ), 

839 ] = None, 

840 proximity_id: Annotated[ 

841 Optional[StrictStr], 

842 Field( 

843 description='Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response. ' 

844 ), 

845 ] = None, 

846 total_hits: Annotated[ 

847 Optional[Annotated[int, Field(le=1000, strict=True, ge=1)]], 

848 Field( 

849 description='When set, the response will include a `total_hits` property with a count of total query matches across all pages, up to the specified limit. ' 

850 ), 

851 ] = None, 

852 tor_node: Annotated[ 

853 Optional[StrictBool], 

854 Field( 

855 description='Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. ' 

856 ), 

857 ] = None, 

858 incremental_identification_status: Annotated[ 

859 Optional[SearchEventsIncrementalIdentificationStatus], 

860 Field( 

861 description='Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. ' 

862 ), 

863 ] = None, 

864 simulator: Annotated[ 

865 Optional[StrictBool], 

866 Field( 

867 description='Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. ' 

868 ), 

869 ] = None, 

870 source: Annotated[ 

871 Optional[Annotated[list[SearchEventsSource], Field(max_length=1)]], 

872 Field( 

873 description='Selects the source of events to search. When omitted, only traditional identification events generated from devices are returned (the default behavior). When set to `edge`, only Automation Intelligence (Edge) events are returned. > Note: The Automation Intelligence API is in public preview testing phase. If you encounter any issues, please [contact](https://fingerprint.com/support/) our support team. ' 

874 ), 

875 ] = None, 

876 _request_timeout: Union[ 

877 None, 

878 Annotated[StrictFloat, Field(gt=0)], 

879 tuple[Annotated[StrictFloat, Field(gt=0)], Annotated[StrictFloat, Field(gt=0)]], 

880 ] = None, 

881 _request_auth: Optional[dict[StrictStr, Any]] = None, 

882 _content_type: Optional[StrictStr] = None, 

883 _headers: Optional[dict[StrictStr, Any]] = None, 

884 ) -> EventSearch: 

885 """Search events 

886 

887 ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events. - Use `start` and `end` to specify the time range of the search. - Use `reverse=true` to sort the results oldest first. - Use `limit` to specify the number of events to return. - Use `pagination_key` to get the next page of results if there are more than `limit` events. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. 

888 

889 :param limit: Maximum number of events to return. Defaults to 10 when omitted. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. 

890 :type limit: int 

891 :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 100 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=S9rgMMUb4z3X5t5pr_tSgoSZlmyF0O8X7kCV2m981-iY1LmRTjraa1rTk3L-hQExnDWCi0RA-zAIjaVSTNO2AN2eqQWgzT0RjbieMxRfSdkM-HmOhdOgdQvYfPG3vqU1DJKh4Q` 

892 :type pagination_key: str 

893 :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). 

894 :type visitor_id: str 

895 :param high_recall_id: The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). 

896 :type high_recall_id: str 

897 :param bot: Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. 

898 :type bot: SearchEventsBot 

899 :param bot_info: Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. 

900 :type bot_info: SearchEventsBotInfo 

901 :param bot_info_category: Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. 

902 :type bot_info_category: List[BotInfoCategory] 

903 :param bot_info_identity: Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. 

904 :type bot_info_identity: List[BotInfoIdentity] 

905 :param bot_info_confidence: Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. 

906 :type bot_info_confidence: List[BotInfoConfidence] 

907 :param bot_info_provider: Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. 

908 :type bot_info_provider: List[str] 

909 :param bot_info_name: Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. 

910 :type bot_info_name: List[str] 

911 :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32