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":{
"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}'