2.2 Retrieving scan reports using data ID
Request |
Value |
Method |
GET |
URL |
https://api.metadefender.com/v4/file/:dataId |
Summary
Retrieve scan status and results after uploading a file.
Retrieve scan results
On MetaDefender Cloud, scans are performed asynchronously and each scan request is tracked by a unique data_id. Initiating a file scan and retrieving the scan results need to be done with two separate API calls. Scan completion can be traced using the property scan_results.progress_percentage from the response. When the value of scan_results.progress_percentage is equal to 100, the scanning is done and you will receive the final scan result. We recommend periodically checking the GET /v4/file/{data_id*} endpoint after you send the file for scanning until the scan is complete.
Alternatively, the webhook functionality can be used.
Request
URL Parameters
|
Description |
Example |
:dataId |
The dataId received on upload |
ZTE2MTIyNkhKeGs5WElSNHhIMVFGLVlUYk85LQ |
Header Parameters
|
Description |
Allowed Values |
Required |
apikey |
gives rights to use the endpoint (token authentication) (API Authentication Mechanisms) |
apikey |
YES |
Response
HTTP Status Codes
Please refer to Status Codes for more information.
Body
Example of in-progress file handling:
{
"data_id"
:
"ZTE2MTIyNkhKeGs5WElSNHhIMVFGLVlUYk85LQ"
,
"status"
:
"inqueue"
,
"in_queue"
:
1
,
"last_updated"
:
"2016-06-21T14:17:59Z"
}
Example of a successful request:
{
"scan_result_history_length"
:
139
,
"file_id"
:
"ZTE2MTIyNkhKeGs5WElSNHg"
,
"data_id"
:
"ZTE2MTIyNkhKeGs5WElSNHhIMVFGLVlUYk85LQ"
,
"scan_results"
: {
"scan_details"
: {
"Lavasoft"
: {
"scan_time"
:
12234
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"STOPzilla"
: {
"scan_time"
:
4109
,
"def_time"
:
"2017-09-07T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Zillya!"
: {
"scan_time"
:
1828
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"VirusBlokAda"
: {
"scan_time"
:
2078
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"TrendMicro"
: {
"scan_time"
:
1938
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"SUPERAntiSpyware"
: {
"scan_time"
:
1781
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"nProtect"
: {
"scan_time"
:
1953
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"NANOAV"
: {
"scan_time"
:
1938
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"F-secure"
: {
"scan_time"
:
2078
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"ESET"
: {
"scan_time"
:
1703
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"a variant of Win32/HackTool.Crack.EN application"
},
"BitDefender"
: {
"scan_time"
:
1859
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Baidu"
: {
"scan_time"
:
2703
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Ahnlab"
: {
"scan_time"
:
1875
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"AegisLab"
: {
"scan_time"
:
1844
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Zoner"
: {
"scan_time"
:
1484
,
"def_time"
:
"2017-09-12T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"ThreatTrack"
: {
"scan_time"
:
1609
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"Trojan.Win32.Generic!BT"
},
"Sophos"
: {
"scan_time"
:
1453
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"App/Steam-AM"
},
"Preventon"
: {
"scan_time"
:
906
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"McAfee"
: {
"scan_time"
:
922
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"K7"
: {
"scan_time"
:
984
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"Unwanted-Program ( 004f3e6f1 )"
},
"Jiangmin"
: {
"scan_time"
:
1641
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"RiskTool.Gamehack.xm"
},
"Hauri"
: {
"scan_time"
:
1609
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"F-prot"
: {
"scan_time"
:
891
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"W32/S-5cce9173!Eldorado"
},
"Fortinet"
: {
"scan_time"
:
1391
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"Riskware/Reloaded"
},
"Filseclab"
: {
"scan_time"
:
1656
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Emsisoft"
: {
"scan_time"
:
922
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"ClamAV"
: {
"scan_time"
:
1594
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"Win.Trojan.Agent-5400546-0"
},
"ByteHero"
: {
"scan_time"
:
891
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"Trojan.Malware.Obscu.Gen.009"
},
"Avira"
: {
"scan_time"
:
984
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"AVG"
: {
"scan_time"
:
984
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Agnitum"
: {
"scan_time"
:
1234
,
"def_time"
:
"2017-08-22T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Ikarus"
: {
"scan_time"
:
328
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"PUA.HackTool.Crack"
},
"Cyren"
: {
"scan_time"
:
875
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"W32/S-5cce9173!Eldorado"
},
"Microsoft Security Essentials"
: {
"scan_time"
:
1906
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Quick Heal"
: {
"scan_time"
:
1813
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
1
,
"threat_found"
:
"Trojan.Generic"
},
"Total Defense"
: {
"scan_time"
:
1484
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"TrendMicro House Call"
: {
"scan_time"
:
1563
,
"def_time"
:
"2017-09-12T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Xvirus Personal Guard"
: {
"scan_time"
:
3969
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Dr.Web Gateway"
: {
"scan_time"
:
1656
,
"def_time"
:
"2017-09-14T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
},
"Vir.IT eXplorer"
: {
"scan_time"
:
1859
,
"def_time"
:
"2017-09-13T00:00:00.000Z"
,
"scan_result_i"
:
0
,
"threat_found"
:
""
}
},
"rescan_available"
:
true
,
"scan_all_result_i"
:
1
,
"start_time"
:
"2017-09-14T14:18:54.204Z"
,
"total_time"
:
12234
,
"total_avs"
:
40
,
"total_detected_avs"
:
12
,
"progress_percentage"
:
100
,
"scan_all_result_a"
:
"Infected"
},
"file_info"
: {
"file_size"
:
1329156
,
"upload_timestamp"
:
"2016-12-26T08:23:23.000Z"
,
"md5"
:
"3642441003AFAE1A776E4EC618DEA974"
,
"sha1"
:
"DB6EE570F574C311D67F263A92DB6D45EAE18954"
,
"sha256"
:
"CA4200D6C6A7275B3EC083FEFE6330A34233D38200843C3853E28D12801FF465"
,
"file_type_category"
:
"E"
,
"file_type_description"
:
"Win32 Dynamic Link Library (generic)"
,
"file_type_extension"
:
"exe/dll/ocx"
,
"display_name"
:
"steam_apirajas.dll"
},
"share_file"
:
1
,
"rest_version"
:
"3"
,
"additional_info"
: [],
"votes"
: {
"up"
:
0
,
"down"
:
0
}
}
Example of a successful request with sanitization:
{
"scan_result_history_length"
:
8
,
"file_id"
:
"bzE5MDIxMkJ5RXEtWmdIRQ"
,
"data_id"
:
"bzE5MDIxMkJ5RXEtWmdIRXJrR2VlNmhNWUg0"
,
"sanitized"
: {
"result"
:
"Allowed"
,
"progress_percentage"
:
100
,
"data_id"
:
"ZDE5MDIyMEJ5RXEtWmdIRS5zYW5pdGl6ZWRCeWx1a2Fic1NF"
,
"reason"
:
""
},
"process_info"
: {
"result"
:
"Blocked"
,
"profile"
:
"Sanitize"
,
"post_processing"
: {
"copy_move_destination"
:
""
,
"converted_to"
:
"xls"
,
"converted_destination"
:
"Ft._immediata_group_7893_2019_02_sanitized_by_OPSWAT_MetaDefender_779e0a0966f348fcaecdacc4f6c47e16.xls"
,
"actions_ran"
:
"Sanitized"
,
"actions_failed"
:
""
},
"file_type_skipped_scan"
:
false
,
"blocked_reason"
:
"Infected"
},
"scan_results"
: {
"scan_details"
: {
"Zillya!"
: {
"threat_found"
:
""
,
"scan_time"
:
2
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T16:58:00.000Z"
},
"Xvirus Personal Guard"
: {
"threat_found"
:
""
,
"scan_time"
:
76
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T09:42:00.000Z"
},
"VirusBlokAda"
: {
"threat_found"
:
""
,
"scan_time"
:
15
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T15:01:00.000Z"
},
"TrendMicro House Call"
: {
"threat_found"
:
"Trojan.69E95BE2"
,
"scan_time"
:
586
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-18T21:48:00.000Z"
},
"TrendMicro"
: {
"threat_found"
:
"Trojan.69E95BE2"
,
"scan_time"
:
502
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-18T21:32:00.000Z"
},
"Total Defense"
: {
"threat_found"
:
""
,
"scan_time"
:
7
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T00:00:00.000Z"
},
"ThreatTrack"
: {
"threat_found"
:
""
,
"scan_time"
:
178
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-18T08:30:00.000Z"
},
"TACHYON"
: {
"threat_found"
:
"Suspicious/X97M.Obfus.Gen.2"
,
"scan_time"
:
31
,
"scan_result_i"
:
2
,
"def_time"
:
"2019-02-19T05:00:00.000Z"
},
"Sophos"
: {
"threat_found"
:
"Troj/DocDl-SAT"
,
"scan_time"
:
12
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T00:43:00.000Z"
},
"SUPERAntiSpyware"
: {
"threat_found"
:
""
,
"scan_time"
:
1153
,
"scan_result_i"
:
0
,
"def_time"
:
"2013-05-22T22:16:00.000Z"
},
"Quick Heal"
: {
"threat_found"
:
"X97M.Downloader.34293"
,
"scan_time"
:
18
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T09:57:00.000Z"
},
"Preventon"
: {
"threat_found"
:
""
,
"scan_time"
:
1070
,
"scan_result_i"
:
3
,
"def_time"
:
"2013-09-18T17:33:00.000Z"
},
"NANOAV"
: {
"threat_found"
:
"Trojan.Ole2.Vbs-heuristic.druvzi"
,
"scan_time"
:
35
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T22:32:00.000Z"
},
"McAfee"
: {
"threat_found"
:
"RDN/Generic Downloader.x"
,
"scan_time"
:
9
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T00:00:00.000Z"
},
"K7"
: {
"threat_found"
:
""
,
"scan_time"
:
4
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-20T01:24:00.000Z"
},
"Jiangmin"
: {
"threat_found"
:
""
,
"scan_time"
:
1090
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-18T23:26:00.000Z"
},
"Ikarus"
: {
"threat_found"
:
""
,
"scan_time"
:
5
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T19:13:00.000Z"
},
"Huorong"
: {
"threat_found"
:
""
,
"scan_time"
:
5
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-18T09:10:00.000Z"
},
"Hauri"
: {
"threat_found"
:
""
,
"scan_time"
:
9
,
"scan_result_i"
:
0
,
"def_time"
:
"2012-08-04T00:00:00.000Z"
},
"Fortinet"
: {
"threat_found"
:
""
,
"scan_time"
:
179
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T00:00:00.000Z"
},
"Filseclab"
: {
"threat_found"
:
""
,
"scan_time"
:
199
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-18T22:50:00.000Z"
},
"F-secure"
: {
"threat_found"
:
""
,
"scan_time"
:
632
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-05T01:33:00.000Z"
},
"F-prot"
: {
"threat_found"
:
"X97M/Agent.gen"
,
"scan_time"
:
4
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-20T02:54:00.000Z"
},
"Emsisoft"
: {
"threat_found"
:
"VB:Trojan.Downloader.JUOD (B)"
,
"scan_time"
:
29
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T15:06:00.000Z"
},
"ESET"
: {
"threat_found"
:
"VBA/TrojanDownloader.Agent.MQM trojan"
,
"scan_time"
:
5
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T00:00:00.000Z"
},
"Cyren"
: {
"threat_found"
:
"X97M/Agent.gen"
,
"scan_time"
:
18
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-20T04:03:00.000Z"
},
"ClamAV"
: {
"threat_found"
:
"Xls.Dropper.Rvaj-6855468-0"
,
"scan_time"
:
94
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T10:36:00.000Z"
},
"ByteHero"
: {
"threat_found"
:
""
,
"scan_time"
:
309
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-19T00:00:00.000Z"
},
"BitDefender"
: {
"threat_found"
:
"VB:Trojan.Downloader.JUOD"
,
"scan_time"
:
32
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-20T01:09:00.000Z"
},
"Baidu"
: {
"threat_found"
:
""
,
"scan_time"
:
549
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-20T08:46:00.000Z"
},
"Avira"
: {
"threat_found"
:
"VBA/Dldr.Agent.xupgw"
,
"scan_time"
:
1
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-18T00:00:00.000Z"
},
"Antiy"
: {
"threat_found"
:
"Trojan[Downloader]/MSOffice.Agent.mqm"
,
"scan_time"
:
16
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T15:30:00.000Z"
},
"Ahnlab"
: {
"threat_found"
:
"X97M/Agent"
,
"scan_time"
:
5
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-20T00:00:00.000Z"
},
"Agnitum"
: {
"threat_found"
:
""
,
"scan_time"
:
2
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-18T14:48:00.000Z"
},
"Vir.IT eXplorer"
: {
"threat_found"
:
"X97M.Downloader.GD"
,
"scan_time"
:
5
,
"scan_result_i"
:
1
,
"def_time"
:
"2019-02-19T14:46:00.000Z"
},
"Vir.IT ML"
: {
"threat_found"
:
""
,
"scan_time"
:
2
,
"scan_result_i"
:
0
,
"def_time"
:
"2019-02-18T14:46:00.000Z"
}
},
"rescan_available"
:
true
,
"scan_all_result_i"
:
1
,
"start_time"
:
"2019-02-20T17:22:27.058Z"
,
"total_time"
:
1166
,
"total_avs"
:
37
,
"total_detected_avs"
:
17
,
"progress_percentage"
:
100
,
"scan_all_result_a"
:
"Infected"
},
"file_info"
: {
"file_size"
:
88576
,
"upload_timestamp"
:
"2019-02-12T08:19:24.000Z"
,
"md5"
:
"D8ED8287B99E918DA0E30EDEC975AD76"
,
"sha1"
:
"1452CE0B131A29DDFC8BA4EF69C77628603CD2AB"
,
"sha256"
:
"88B323D7AFE5D9715603570A04B32D35384292739A7B4F47B2B409863A4F822C"
,
"file_type_category"
:
"D"
,
"file_type_description"
:
"Microsoft Excel 97-2003 Workbook"
,
"file_type_extension"
:
"xlsx"
,
"display_name"
:
"Ft._immediata_group_7893_2019_02.xls"
},
"share_file"
:
1
,
"rest_version"
:
"4"
,
"additional_info"
: [],
"votes"
: {
"up"
:
0
,
"down"
:
0
}
}
Example when a result is not found:
{
"error"
: {
"code"
:
404004
,
"messages"
: [
"The data_id was not found"
]
}
}
Descriptions of responses:
Please refer to Retrieving scan reports using a data hash
The "in_queue" value represents the total number of files in the queue at the time of polling. The processing order is FIFO, but there is no way to see how many messages are in front of the polled one. Sometimes this number will increase during polling, but that does not mean that the message is losing its priority in the queue.
Errors
Please refer to Errors for more information.
Sample code (Node.js)
var http = require(
"https"
);
var options = {
"method"
:
"GET"
,
"hostname"
: [
"api"
,
"metadefender"
,
"com"
],
"path"
: [
"v4"
,
"file"
,
"ZTE2MTIyNkhKeGs5WElSNHhIMVFGLVlUYk85LP"
],
"headers"
: {
"apikey"
: process.env.APIKEY
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on(
"data"
, function (chunk) {
chunks.push(chunk);
});
res.on(
"end"
, function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
Sample code (cURL)
curl -X GET \
https:
//api.metadefender.com/v4/file/ZTE2MTIyNkhKeGs5WElSNHhIMVFGLVlUYk85LP \
-H
"apikey: ${APIKEY}"
\