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 /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

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",
"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:

{
"success": false,
"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}" \