3.3 Retrieving scan history

Request

Value

Method

GET

URL

https://api.metadefender.com/v3/hash/:hash/scanhistory

Summary

Look up the scan history of a hash by MD5, SHA1, or SHA256. The scan history is paginated for easy consumption, because some scan histories have hundreds of entries.

Request

URL Parameters

 

Description

Example

:hash

MD5, SHA1, or SHA256 of a file

6A5C19D9FFE8804586E8F4C0DFCC66DE

Header Parameters

 

Description

Allowed Values

Required

Authorization

give rights to use the endpoint (token authentication) (API Authentication Mechanisms)

apikey

YES

Query Parameters

 

Description

Allowed Values

Default

Required

limit

Pagination - How many entries to return

Number

0

NO

offset

Pagination - How many entries to skip (sorted chronologically)

Number

0

NO

Response

HTTP Status Codes

Please refer to Status Codes for more information.

Body

Example of successful scan request (offset = 0, limit = 3:

{
"success": true,
"data": {
"md5": "4C2C02AFFA477C7B5E9572E14D2C7FC4",
"sha1": "AFDF136ED77EDE14EC69A693B8747014DD43414A",
"sha256": "DEEE7E51D7F381DBEE8279AA402C6488EC12765E935475C780AACBB186B0F5C2",
"scan_result_history": [
{
"total_detected_avs": 0,
"total_avs": 43,
"scan_all_result_i": 0,
"start_time": "2015-02-19T13:42:25.431Z",
"data_id": "c6ba844a7c02483bba4b5ac068e7cdde"
},
{
"total_detected_avs": 0,
"total_avs": 43,
"scan_all_result_i": 0,
"start_time": "2015-02-19T13:46:22.477Z",
"data_id": "f21bc4d540ab4f8f877f418464bf8681"
},
{
"total_detected_avs": 0,
"total_avs": 43,
"scan_all_result_i": 0,
"start_time": "2015-02-19T13:50:30.120Z",
"data_id": "febcf43012104c2eb2930843160a85df"
}
]
}
}

Example of failed scan request:

{
"success": false,
"error": {
"code": 404003,
"messages": [
"The hash was not found"
]
}
}

Descriptions of response:

data.scan_result_history.scan_all_result_i

The scan returned code. Please refer to Description on scan result codes for more information.

data.scan_result_history.start_time

The time when the scan has started

data.scan_result_history.total_avs

The total number of AVs returned in the result

data.scan_result_history.total_detected_avs

The total number of AVs reporting this file as infected

data.scan_result_history.data_id

Unique identifier for this particular scan of the file

More levels for file_info level:

upload_timestamp

First time the file is uploaded to the server (even if file is rescanned this value will be preserved).

file_type_category

High level categorization of the file type.

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": "/v2/hash/E71A6D8760B37E45FA09D3E1E67E2CD3/scanhistory",
"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/hash/E71A6D8760B37E45FA09D3E1E67E2CD3/scanhistory?offset=0&limit=10 \
-H 'apikey: ${APIKEY}'