Historic multi-AV scan records (TCA-0103)

The Historic Multi-AV Scan Records service returns the multi-AV scan reports for a sample. Each report lists the antivirus scanners that scanned the sample and the result from each scanner. By default, the service returns the latest report. Set the history parameter to also get earlier reports.

The service supports single and bulk queries.

This API is rate limited to 400 requests per second. If you go over the rate limit, or if you reach your daily or monthly quota, the service returns HTTP status code 429. See Response status codes.

Common use cases

The service looks up the hash in Spectra Intelligence and returns the antivirus results that the system has stored for that file. It doesn't scan the file.

• Evidence behind a verdict. File reputation (TCA-0101) gives you the number of scanners that detected a sample. This service tells you which scanners they were and what each one reported. Read results for the per-scanner results and scanners for the engine version and update time of each scanner.
• Detection trend over time. Set history=true to get up to 20 reports, newest first. Compare scanner_match and scanner_count across the reports to see how the detection count changed.
• Bulk checking. A bulk query takes up to 100 hashes per request. Match each entry in samples to your input by its hash. Don't use the order of the entries.

If the service has no multi-AV data for a hash, that doesn't mean the file is safe. It means that Spectra Intelligence hasn't scanned the file. Upload the sample with the File upload (TCA-0202/0203) API. If the latest report is old, request a new scan with the Reanalyze file (TCA-0205) API.

The antivirus results change over time. Spectra Intelligence scans samples again, and scanners add and change detections. A stored scanner_match value can become incorrect. Query the hashes that are important to you again, and use last_scanned_on to find the time of the latest report.

General information about requests and responses

• The service is available at https://data.reversinglabs.com and uses HTTP Basic authentication. See Getting started for credentials and your first request.
• All requests support the format parameter. It has two options: xml and json.
• The default response format is xml. For bulk queries, the default response format is the same as the post_format.
• A bulk request must not contain more than 100 hashes. A request that contains more than 100 hashes returns HTTP status code 413.
• POST requests must set the Content-Type header to application/octet-stream. See Content-Type for bulk requests.
• The hash_type value is not case-sensitive. SHA1 and sha1 give the same result.
• Timestamps use the format YYYY-MM-DDTHH:MM:SS. The values have no time zone offset.
• For the full list of response codes, see Response status codes.

Multi-AV scan report

This query returns the latest multi-AV scan report for one sample.

View OpenAPI Specification

Request

GET /api/xref/v2/query/{hash_type}/{hash_value}

• hash_type
  • Specifies the hash type that the request uses. Supported values: md5, sha1, sha256
  • Required
• hash_value
  • The hash of the file that you request data for. The value must be a valid hash of the type that the hash_type parameter specifies.
  • Required
• format
  • The response format. Supported values: xml, json. The default is xml.
  • Optional
• history
  • Set to true to get up to 20 reports instead of only the latest one. Supported values: true, false. The default is false. See Multi-AV scan history.
  • Optional

If Spectra Intelligence has no multi-AV data for the hash, the service returns HTTP status code 404.

Response

This response is for a sample that some of the scanners detected. The scanners and results lists are shortened to three entries.

{
  "rl": {
    "sample": {
      "sha1": "7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb",
      "md5": "e196466d4597bef92404f73892db5606",
      "sha256": "000e2bd65848674562b615696a28f2cb3ed974a3600dbfa52da1c6240bef4e76",
      "sha384": "23e0bf3a284ae10edfbc5f155eb9effa92678be7eae67bc68dd6f4cb99f4f458a2cb986ba6035fb24d14aa65ab7efb35",
      "sha512": "e9f7d04c903d28fe00a99aa2043ac9172e4c1a8d6a6c2bc06d8bd7fd656c1aeb613659a24eaf76f00553696a964529b50262214632c55138c5aa11a5b4e66b45",
      "ripemd160": "76a939882589b74cab5ff136f5724ae075c6496a",
      "sample_type": "PE32 executable (GUI) Intel 80386, for MS Windows, 11 sections",
      "sample_size": 417792,
      "single_scan": false,
      "first_seen_on": "2013-10-26T17:55:00",
      "last_seen_on": "2023-12-22T07:22:00",
      "first_scanned_on": "2013-10-26T17:55:00",
      "last_scanned_on": "2023-12-22T07:22:00",
      "xref": [
        {
          "scanner_match": 7,
          "scanner_count": 23,
          "scanned_on": "2023-12-22T07:22:00",
          "scanners": [
            {
              "name": "scanner-1",
              "version": "<engine package file>",
              "timestamp": "2023-12-21T09:45:00"
            },
            {
              "name": "scanner-2",
              "version": "<engine package file>",
              "timestamp": "2023-12-22T04:55:00"
            },
            {
              "name": "scanner-3",
              "version": "<engine package file>",
              "timestamp": "2023-12-22T05:45:00"
            }
          ],
          "results": [
            {
              "scanner": "scanner-1",
              "result": "<detection name>"
            },
            {
              "scanner": "scanner-2",
              "result": ""
            },
            {
              "scanner": "scanner-3",
              "result": ""
            }
          ]
        }
      ]
    }
  }
}

The fields in sample are always returned.

• sha1, md5, sha256, sha384, sha512, ripemd160
  • The hashes of the sample. You get all of them, whichever hash type you query with.
• sample_type
  • The file type description, for example PE32 executable (GUI) Intel 80386, for MS Windows.
• sample_size
  • The size of the sample, in bytes.
• single_scan
  • true if Spectra Intelligence has only one multi-AV scan report for the sample. Otherwise, false.
• first_seen_on
  • The time when Spectra Intelligence first received or scanned the sample.
• last_seen_on
  • The time when Spectra Intelligence last received or scanned the sample.
• first_scanned_on
  • The time of the first multi-AV scan of the sample. This scan can be older than the oldest report that the service returns, because the history holds only the 20 most recent reports.
• last_scanned_on
  • The time of the latest multi-AV scan of the sample.
• xref
  • The list of multi-AV scan reports. Without history=true, the list has one item: the latest report. See Scan report object.

Scan report object

Each item in xref is one multi-AV scan report.

• scanned_on
  • The time of the scan.
• scanner_count
  • The number of scanners in the scan. This number includes scanners that failed to scan the sample. It is equal to the number of entries in scanners. The number isn't fixed. It can be different for each sample and for each scan of the same sample.
• scanner_match
  • The number of scanners that detected the sample in this scan. It is equal to the number of entries in results that have a non-empty result.
• scanners
  • The scanners in the scan, with the engine data for each one. See Scanner object.
• results
  • The result from each scanner that completed the scan. A scanner that failed doesn't have an entry. If all scanners failed, the results field is not in the report. See Result object.

Don't count the entries in results to get the number of detections. The list also contains the scanners that didn't detect the sample. Use scanner_match, or count the entries with a non-empty result.

The scanners and results lists don't use the same order. To connect a result to its engine data, match results[].scanner to scanners[].name.

Scanner object

{
  "name": "scanner-1",
  "version": "<engine package file>",
  "timestamp": "2023-12-21T09:45:00"
}

• name
  • The name of the scanner.
• version
  • The name of the antivirus engine file, or of its update, that the scanner used for this scan.
• timestamp
  • The time of the scanner update. The update can be to the antivirus database or to the antivirus engine.

Result object

{
  "scanner": "scanner-1",
  "result": "<detection name>"
}

• scanner
  • The name of the scanner. It matches name in the Scanner object.
• result
  • The detection name that the scanner reported. An empty string means that the scanner didn't detect the sample.

Multi-AV scan bulk report

This query returns the same data as the single query, for up to 100 hashes in one request. It uses fewer network resources than many single queries.

View OpenAPI Specification

Request

POST /api/xref/v2/bulk_query/{post_format}

• post_format
  • The format of the request body. Supported values: xml, json. The response uses the same format, unless you set format.
  • Required
• format
  • The response format. Supported values: xml, json.
  • Optional
• history
  • Set to true to get up to 20 reports for each sample. The default is false. See Multi-AV scan history.
  • Optional

Request body

With post_format set to json:

{
  "rl": {
    "query": {
      "hash_type": "sha1",
      "hashes": [
        "a7afddb68260a60f86c02a021efba7f216c2e7cf",
        "ca03064987d3c4465f91552ba8b6a883eecfd3e5",
        "b363713a938afcd3c74603827fab79e935b2b09b",
        "example_of_a_wrong_hash"
      ]
    }
  }
}

With post_format set to xml, the same request puts each hash in an item element:

<rl>
  <query>
    <hash_type>sha1</hash_type>
    <hashes>
      <item>a7afddb68260a60f86c02a021efba7f216c2e7cf</item>
      <item>ca03064987d3c4465f91552ba8b6a883eecfd3e5</item>
      <item>b363713a938afcd3c74603827fab79e935b2b09b</item>
      <item>example_of_a_wrong_hash</item>
    </hashes>
  </query>
</rl>

The XML declaration (<?xml version="1.0" encoding="UTF-8"?>) is optional. Both formats return the same data.

• hash_type
  • The hash type of all hashes in the request. Supported values: md5, sha1, sha256
• hashes
  • The list of hashes. It must contain from 1 to 100 hashes. An empty list returns HTTP status code 400.

Content-Type for bulk requests

Set the Content-Type header to application/octet-stream. The service reads the request body as JSON or XML according to post_format. Some other values also work, for example application/json for a JSON body. Don't use a form content type. With application/x-www-form-urlencoded or multipart/form-data, the service can't read the body and returns HTTP status code 400.

Some HTTP clients set a form content type by default. For example, curl sends application/x-www-form-urlencoded with --data and --data-binary unless you set the header yourself:

curl --request POST 'https://data.reversinglabs.com/api/xref/v2/bulk_query/json' \
  --user <username>:<password> \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @request.json

Response

This response is for the request body above. Two hashes are known, one is unknown, and one is not a valid SHA1 hash. The scanners and results lists are shortened to three entries.

{
  "rl": {
    "samples": [
      {
        "sha1": "a7afddb68260a60f86c02a021efba7f216c2e7cf",
        "md5": "ecae13117d6f0584c25a9da6c8f8415e",
        "sha256": "3316348dbadfb7b11c7c2ea235949419e23f9fa898ad2c198f999617912a9925",
        "sha384": "ec635fbf3c47a97bf33fc24fe6ee7b04da172537ad8eb01885f29432614c433398789505277ed350ad56648af98c207e",
        "sha512": "ee021c5aa94c55f1dbbe287200618d386799f21ce4e35af71c9e7474267ebaf5fde5436ea44d689c8abd9dbb24e76da9493f982453cad987d1ca003f9eb9ef34",
        "ripemd160": "3f756169279d4a50ee2931f653a1020c39951235",
        "sample_type": "ASCII text, with no line terminators",
        "sample_size": 4,
        "single_scan": false,
        "first_seen_on": "2013-12-14T07:53:00",
        "last_seen_on": "2026-03-19T12:04:00",
        "first_scanned_on": "2013-12-14T07:53:00",
        "last_scanned_on": "2026-03-19T12:04:00",
        "xref": [
          {
            "scanner_match": 0,
            "scanner_count": 38,
            "scanned_on": "2026-03-19T12:04:00",
            "scanners": [
              {
                "name": "scanner-1",
                "version": "<engine package file>",
                "timestamp": "2026-03-19T10:02:00"
              },
              {
                "name": "scanner-2",
                "version": "<engine package file>",
                "timestamp": "2026-03-19T10:02:00"
              },
              {
                "name": "scanner-3",
                "version": "<engine package file>",
                "timestamp": "2026-03-19T10:03:00"
              }
            ],
            "results": [
              {
                "scanner": "scanner-1",
                "result": ""
              },
              {
                "scanner": "scanner-2",
                "result": ""
              },
              {
                "scanner": "scanner-3",
                "result": ""
              }
            ]
          }
        ]
      },
      {
        "sha1": "b363713a938afcd3c74603827fab79e935b2b09b",
        "md5": "3c78b35502b2693fefdfc51cba3a53a5",
        "sha256": "36bde66f289a35683683b041c6d8f418a5f36607b547da25d00ad55891e80b88",
        "sha384": "ce5d21c271776c88490850cad79c5794f7822165e402cf0abde2be1b5ebeb4e988eee6d9ce22ea06babe7ee3233e2c94",
        "sha512": "58941c13ad37895a59ef321bbac1c4818734c0ea305cee3eaab38b3d3ee90005843c334eff1a6d1f4bf9f90c0f1d458dac833ed24a9153761935d355fb0dbef6",
        "ripemd160": "1f0e050f8570a9e4a99ad38ef05903efac03db37",
        "sample_type": "ASCII text, with no line terminators",
        "sample_size": 6,
        "single_scan": false,
        "first_seen_on": "2018-05-29T05:53:41",
        "last_seen_on": "2026-03-19T12:08:00",
        "first_scanned_on": "2018-05-29T06:11:00",
        "last_scanned_on": "2026-03-19T12:08:00",
        "xref": [
          {
            "scanner_match": 0,
            "scanner_count": 38,
            "scanned_on": "2026-03-19T12:08:00",
            "scanners": [
              {
                "name": "scanner-1",
                "version": "<engine package file>",
                "timestamp": "2026-03-19T10:02:00"
              },
              {
                "name": "scanner-2",
                "version": "<engine package file>",
                "timestamp": "2026-03-19T10:02:00"
              },
              {
                "name": "scanner-3",
                "version": "<engine package file>",
                "timestamp": "2026-03-19T10:03:00"
              }
            ],
            "results": [
              {
                "scanner": "scanner-1",
                "result": ""
              },
              {
                "scanner": "scanner-2",
                "result": ""
              },
              {
                "scanner": "scanner-3",
                "result": ""
              }
            ]
          }
        ]
      }
    ],
    "unknown_hashes": [
      "ca03064987d3c4465f91552ba8b6a883eecfd3e5"
    ],
    "invalid_hashes": [
      "example_of_a_wrong_hash"
    ]
  }
}

• samples
  • One item for each hash that has multi-AV data. Each item has the same fields as sample in the single query response.
• unknown_hashes
  • The hashes from the request that Spectra Intelligence has no multi-AV data for.
• invalid_hashes
  • The hashes from the request that are not valid hashes of the type that hash_type specifies. For example, an MD5 hash in a request with hash_type set to sha1 is in this list.

Each hash from the request is in one of the three lists. If you send the same hash two times, samples contains it two times.

The service returns a list only if it has entries. For example, if no hash in the request is known, the response has no samples field:

{
  "rl": {
    "unknown_hashes": [
      "ca03064987d3c4465f91552ba8b6a883eecfd3e5"
    ]
  }
}

The order of the items in samples is not guaranteed. To match an item to your request, use the hash field for the hash_type that you sent. For example, if you queried SHA1 hashes, use sha1.

XML response

An XML response has the same fields. Each entry in a list is an item element. An empty result is an empty element. This excerpt shows the start of the response above, with one scanner:

<?xml version="1.0" encoding="utf-8"?>
<rl>
  <samples>
    <item>
      <sha1>a7afddb68260a60f86c02a021efba7f216c2e7cf</sha1>
      <md5>ecae13117d6f0584c25a9da6c8f8415e</md5>
      <single_scan>false</single_scan>
      <xref>
        <item>
          <scanner_match>0</scanner_match>
          <scanner_count>38</scanner_count>
          <scanned_on>2026-03-19T12:04:00</scanned_on>
          <scanners>
            <item>
              <name>scanner-1</name>
              <version>engine-package-file</version>
              <timestamp>2026-03-19T10:02:00</timestamp>
            </item>
          </scanners>
          <results>
            <item>
              <scanner>scanner-1</scanner>
              <result></result>
            </item>
          </results>
        </item>
      </xref>
    </item>
  </samples>
  <unknown_hashes>
    <item>ca03064987d3c4465f91552ba8b6a883eecfd3e5</item>
  </unknown_hashes>
  <invalid_hashes>
    <item>example_of_a_wrong_hash</item>
  </invalid_hashes>
</rl>

The service returns XML without line breaks or indentation. The excerpt is formatted for reading, and most sample fields are removed.

Multi-AV scan history

The single and bulk queries both support the history parameter. When history is true, xref contains up to 20 reports, newest first. The first item is the latest report, which is the same report that you get without history. All other fields are the same as in the response without history.

Request

GET /api/xref/v2/query/{hash_type}/{hash_value}?history=true

POST /api/xref/v2/bulk_query/{post_format}?history=true

The history parameter accepts only true and false. Other values return HTTP status code 400.

Response

This excerpt shows the first two reports for the sample from the single query response. The other sample fields are removed, and the scanners and results lists are shortened to one entry.

{
  "rl": {
    "sample": {
      "sha1": "7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb",
      "single_scan": false,
      "xref": [
        {
          "scanner_match": 7,
          "scanner_count": 23,
          "scanned_on": "2023-12-22T07:22:00",
          "scanners": [
            {
              "name": "scanner-1",
              "version": "<engine package file>",
              "timestamp": "2023-12-21T09:45:00"
            }
          ],
          "results": [
            {
              "scanner": "scanner-1",
              "result": "<detection name>"
            }
          ]
        },
        {
          "scanner_match": 12,
          "scanner_count": 37,
          "scanned_on": "2023-05-12T15:29:00",
          "scanners": [
            {
              "name": "scanner-1",
              "version": "<engine package file>",
              "timestamp": "2023-05-12T15:01:00"
            }
          ],
          "results": [
            {
              "scanner": "scanner-1",
              "result": "<detection name>"
            }
          ]
        }
      ]
    }
  }
}

The number of scanners can change from one report to the next, so compare scanner_match with scanner_count in the same report. Two reports can have the same scanned_on value.

Examples

Single query - changing the response format

/api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=json
/api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=xml

Single query - changing the hash type

These requests return the same sample:

/api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=json
/api/xref/v2/query/md5/e196466d4597bef92404f73892db5606?format=json
/api/xref/v2/query/sha256/000e2bd65848674562b615696a28f2cb3ed974a3600dbfa52da1c6240bef4e76?format=json

Bulk query - changing the POST format

/api/xref/v2/bulk_query/json
/api/xref/v2/bulk_query/xml

Response status codes

This API returns custom messages for some status codes. For the full list of HTTP status codes, see Response status codes in the General section. Error responses are plain text.

Code	Message	Description
400	Invalid hash value	The hash is not valid, or it doesn't match the hash type.
	Invalid hash type	The hash type is not supported. Supported types are md5, sha1, and sha256.
	Invalid history parameter	The history value is not true or false.
	unknown post format	The post_format value is not xml or json. Bulk queries only.
	Validation message	The hashes list in the request body is empty. Bulk queries only.
	Invalid username	The username in the Authorization header has unrecognized characters, or is not valid for another reason.
	Parsing error description	The service couldn't parse the request. For example, the JSON is not valid, or a required parameter is missing. A JSON request body sent with a form content type returns No JSON object could be decoded.
	(empty)	The service couldn't parse an XML request body. For example, the body was sent with a form content type. See Content-Type for bulk requests.
401	Invalid password or user	The credentials are not correct.
403	User disabled	The user account that sent the request is disabled.
	User not allowed	The user account doesn't have the required permissions.
404	No XREF for sample	Spectra Intelligence has no multi-AV data for the hash. Single queries only. A bulk query puts the hash in unknown_hashes.
413		The request contains more than 100 hashes. Bulk queries only.

See also

• File reputation (TCA-0101) - the classification of a sample, with the detection counts that this service gives the detail for
• File analysis (TCA-0104) - the full static and dynamic analysis data for a sample, which also includes the multi-AV history in its xref section
• File upload (TCA-0202/0203) - how to upload a sample when Spectra Intelligence has no multi-AV data for its hash
• Reanalyze file (TCA-0205) - how to request a new multi-AV scan when the latest report is old
• Analysis rescans - when Spectra Intelligence scans samples again automatically