2.2 Retrieving scan reports using data ID
|
Request |
Value |
|
Method |
GET |
|
URL |
https://api.metadefender.com/v2/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 /v2/file/{data_id*} endpoint after you send the file for scanning until the scan is complete.
Request
URL Parameters
|
|
Description |
Example |
|
:dataId |
The dataId received on upload |
ZTE2MTIyNkhKeGs5WElSNHhIMVFGLVlUYk85LQ |
Header Parameters
|
|
Description |
Allowed Values |
Required |
|
apikey |
give rights to use the endpoint (token authentication) (API Authentication Mechanisms) |
apikey |
YES |
|
file_metadata |
Retrieve file metadata and hash_results |
0 / 1 |
NO |
Response
HTTP Status Codes
Please refer to Status Codes for more information.
Body
Example of in-progress file handling
{ "data_id": "692fd1c79ada4e2694f88d11a7c9a21c", "status": "inqueue", "in_queue": 1, "last_updated": "2016-06-21T14:17:59Z"}Example of successful scan request
{ "file_id" : "5260b0b10671380cc8f08c10", "top_threat" : 847, "scan_results" : { "scan_details" : { "ClamWin" : { "scan_result_i" : 0, "threat_found" : null, "def_time" : "2013-10-09T07:00:00z", "scan_time" : 10002.0 } "ESET" : { "scan_result_i" : 0, "threat_found" : null, "def_time" : "2013-10-09T07:00:00z", "scan_time" : 10001.0 } "Norman" : { "scan_result_i" : 0, "threat_found" : null, "def_time" : "2013-10-09T07:00:00Z", "scan_time" : 10026.0 } "TotalDefense" : { "scan_result_i" : 0, "threat_found" : null, "def_time" : "2013-10-09T07:00:00Z", "scan_time" : 10097.0 } }, "rescan_available" : false, "data_id" : "dcab095cdda14465a935e19595109aaf", "scan_all_result_i" : 0, "start_time" : "2013-10-18T03:53:11.135Z", "total_time" : 10097, "total_avs" : 4, "progress_percentage" : 100, "in_queue" : 0, "scan_all_result_a" : "Clean" }, "file_info" : { "file_size" : 140, "upload_timestamp" : "2013-10-18T03:53:11.114Z", "md5" : "090240882000639EC727A09C04A6DC8D", "sha1" : "852A01FA563C34BA35CA5890B7268872B52C0BF0", "sha256" : "8DCBB493207B1446F4413BC7B369552EF8CAAA8DBEAD8512A5A1296CCEF0F71A", "file_type_category" : "T", "file_type_description" : "ASCII text, with CRLF line terminators", "file_type_extension" : "-", "display_name" : "File name unknown" "pe_info" : { "imphash" : "f34d5f2d4577ed6d9ceec516c1f5a744", "vs_version_info" : { "legal_copyright" : "Copyright © 2013 WinterSoft", "internal_name" : "TSULoader", "company_name" : "WinterSoft", "comments" : "WinNT (x86) Unicode Lib Rel", "product_name" : "WinterSoft", "product_version" : "1.0.0.1", "file_description" : "Installer for WinterSoft", "original_filename" : "TSULoader.exe" } "headers" : { "machine_type" : "IMAGE_FILE_MACHINE_I386", (1) "compilation_time" : "2012-11-08T00:29:14Z", "number_of_sections" : 3, "pointer_to_symbol_table" : "0", "number_of_symbols" : 0, "characteristics" : [ "IMAGE_FILE_32BIT_MACHINE", "IMAGE_FILE_EXECUTABLE_IMAGE" ] (2) }, "optional_headers" : { "pe_type" : "0x10b", "linker_version" : "8.0", "entry_point" : "0x14d46", "subsystem" : "IMAGE_SUBSYSTEM_WINDOWS_GUI", (3) "subsystem_version" : "4.0", "image_version" : "0.0", "image_size" : 196608, "code_size" : 77312, "os_version" : "4.0", "checksum" : "0", "initialized_data_size" : 93696, "uninitialized_data_size" : 0 }, "section_headers" : [ { "name" : ".text", "virtual_address" : "0x2000", "virtual_size" : 77132, "raw_size" : 77312, "entropy" : 5.7175721045, "md5" : "1e562bb56a7adf27cf3d123c834a21e8", "number_of_relocations" : 0, "number_of_linenumbers" : 0, "pointer_to_raw_data" : "0x200", "pointer_to_relocations" : "0x0", "pointer_to_linenumbers" : "0x0", "characteristics" : [ "IMAGE_SCN_MEM_EXECUTE", "IMAGE_SCN_CNT_CODE", "IMAGE_SCN_MEM_READ" ] (4) },... ], "imported_dlls" : [ { "name" : "mscoree.dll", "functions" : [ "_CorExeMain" ] } ], "exported_functions" : [ ], "resource_info" : [ { "name" : "RT_ICON", "resource_ids" : [ { "name" : "0x50", "resource_langs" : [ "LANG_NEUTRAL" ] }, { "name" : "0x51", "resource_langs" : [ "LANG_NEUTRAL" ] }, { "name" : "0x52", ... ] }, { "name" : "RT_GROUP_ICON", "resource_ids" : [ { "name" : "ICON", "resource_langs" : [ "LANG_NEUTRAL" ] } ] }... ] }, "additional_info" : { "file_identification" : { "TrID" : [ { "file_type" : "Autodesk FLIC Image File (extensions: flc, fli, cel)", "file_ext" : "CEL", "matching_points" : 7 }, { "file_type" : "DOS Executable Generic", "file_ext" : "EXE", "matching_points" : 2000 }] }, "exif_info" : [{ "key" : "Subsystem", "value" : "Windows GUI" }, { "key" : "File Version Number", "value" : "1.3.27.5" }, { "key" : "Product Version Number", "value" : "1.3.27.5" }, { "key" : "File Flags Mask", "value" : "0x003f" } ] } }, "data_id" : "dcab095cdda14465a935e19595109aaf", "hash_results" : { "nist" : { .... } ... } }Example of successful scan request with sanitization
{ "file_id":"ZzE2MTEyMnIxY2xHaGtWek14", "data_id":"ZzE2MTEyMnIxY2xHaGtWek14UzFzbHpuMUV6Zmc", "sanitized":{ "file_path":"https://s3-us-west-2.amazonaws.com/g.files.metadefender.com/dt%3D161122/r1clGhkVzMx.sanitized?AWSAccessKeyId=AKIAJATVWRQL5FM5ZFNQ&Expires=1479850861&Signature=OaQI5T8PshJh6iTESFj%2FZUfXNHk%3D&response-content-disposition=attachment%3B%20filename%3DScreenshot%20from%202016-11-22%20125042.png", "data_id":"ZzE2MTEyMnIxY2xHaGtWek14cjEyaHlFR01n", "result":"Allowed" }, "scan_results":{ "scan_details":{ "Ahnlab":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":78 }, "Antiy":{ "threat_found":"", "scan_result_i":3, "def_time":"2016-11-07T00:00:00Z", "scan_time":0 }, "Avira":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":63 }, "Fortinet":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":735 }, "F-prot":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":750 }, "Ikarus":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":344 }, "K7":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":63 }, "McAfee":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":735 }, "nProtect":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":782 }, "Preventon":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":735 }, "QuickHeal":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":63 }, "Sophos":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":78 }, "TotalDefense":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":47 }, "Zillya!":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":266 }, "Zoner":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-21T00:00:00Z", "scan_time":782 }, "AegisLab":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":1516 }, "Agnitum":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":844 }, "AVG":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":938 }, "Baidu":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":1531 }, "BitDefender":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":938 }, "ByteHero":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":844 }, "ClamAV":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":985 }, "CYREN":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":891 }, "DrWebGateway":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":844 }, "Emsisoft":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":453 }, "ESET":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":750 }, "Filseclab":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-05T00:00:00Z", "scan_time":1063 }, "F-secure":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":1360 }, "Hauri":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":844 }, "Jiangmin":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":1766 }, "Microsoft":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-21T00:00:00Z", "scan_time":985 }, "NANOAV":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":985 }, "SUPERAntiSpyware":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":1797 }, "Symantec":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":797 }, "ThreatTrack":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":922 }, "TrendMicro":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":1078 }, "TrendMicroHouseCall":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-21T00:00:00Z", "scan_time":1438 }, "VirITeXplorer":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":844 }, "VirusBlokAda":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":922 }, "Xvirus":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-16T00:00:00Z", "scan_time":1016 }, "Lavasoft":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-22T00:00:00Z", "scan_time":4016 }, "STOPzilla":{ "threat_found":"", "scan_result_i":0, "def_time":"2016-11-21T00:00:00Z", "scan_time":4969 } }, "rescan_available":true, "data_id":"ZzE2MTEyMnIxY2xHaGtWek14UzFzbHpuMUV6Zmc", "scan_all_result_i":0, "start_time":"2016-11-22T20:50:49.751Z", "total_time":4969, "total_avs":42, "total_detected_avs":0, "progress_percentage":100, "in_queue":0, "scan_all_result_a":"Clean" }, "file_info":{ "file_size":568086, "upload_timestamp":"2016-11-22T20:50:49.751Z", "md5":"86E434EB0D2528F597080903BDDB076B", "sha1":"D59C0A38DA1FD246ABAC51887B67EA41CCF448E3", "sha256":"BCE92B0054542C1A0B2DAD22BD9FC044ABCF5F232FFCAFA33950E5AC652DF2E6", "file_type_category":"G", "file_type_description":"Portable Network Graphics", "file_type_extension":"png", "display_name":"Screenshot from 2016-11-22 125042.png" }, "top_threat":-1}Example when a result is not found:
{ "4f84e3b096d54908963d037b5457bf27": "Not Found" }Descriptions of responses:
|
newer |
the data_id of the newest scan result for this file |
For more fields, please refer to Retrieving scan reports using a data hash
The "in_queue" value represents the total number of files in 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 loosing it's 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", "port": null, "path": "/v2/file/6d21e9cdfd3b42b49e3c26d79d1e26c2", "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/v2/file/6d21e9cdfd3b42b49e3c26d79d1e26c2 \ -H 'apikey: ${APIKEY}'