# Report Summary API — Get Analysis Report Summaries

> Retrieve analysis report summaries for samples on Spectra Analyze. POST /api/samples/v2/list/ returns classification, risk, and metadata.

## Retrieve a summary analysis report for local samples

```
POST /api/samples/v2/list/
```

Get a summary of the analysis report for a single sample or for multiple samples. The samples must be present on the Spectra Analyze appliance. Sample hashes must be provided using the `hash_values` parameter in the request.

If the optional `fields` parameter is not included in the request, all available report fields for the requested sample(s) are returned in the response. The fields “ticore”, “ticloud”, “summary” and “aliases” are returned only if they are explicitly specified in the request.

### Request Format

**Request Parameters**

| NAME                              | REQUIRED | DESCRIPTION                                                  | TYPE                        |
| :-------------------------------- | :------- | :----------------------------------------------------------- | :-------------------------- |
| hash_values                       | Required | One or more hashes of samples for which the analysis report should be returned. The samples must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5. All hashes in a request must be of the same type. | array                       |
| fields                            | Optional | Comma-separated list of report fields to include in the response. When this parameter is not included in the request, all available fields are returned, except “ticore”, “ticloud”, “summary” and “aliases”. Supported values: `id, sha1, sha256, sha512, md5, category, file_type, file_subtype, identification_name, identification_version, file_size, extracted_file_count, local_first_seen, local_last_seen, classification_origin, classification_reason, classification_source, classification, riskscore, classification_result, ticore, tags, summary, ticloud, aliases, networkthreatintelligence, domainthreatintelligence, imphash, discussion, proposed_filename, av_scanners, av_scanners_summary` Network and domain threat intelligence results won’t be applied unless the parameter `include_networkthreatintelligence` is set to true. | array                       |
| include_networkthreatintelligence | Optional | Include or exclude network or domain threat intelligence. If this is set to true, parameters `networkthreatintelligence` and `domainthreatintelligence` have to be included in the `fields` parameter. Applies only to URLs, not files. | boolean (but inside quotes) |
| skip_reanalysis                   | Optional | Whether to reanalyze a file when fetching its report. False by default (if omitted, files will be reanalyzed when their reports are fetched). | boolean (but inside quotes) |

**Request Examples**

**cURL**

```bash
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/samples/v2/list/' \
  --header 'Authorization: Token exampletoken' \
  --header 'Content-Type: application/json' \
  --data '{"hash_values":["9dc5e23c7ab2692b83f0690a736b123a1837ae56", "4b21a49eadac1bc01477eff778041fdb765b8139"]}'
```

**cURL with optional parameters**

```bash
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST 'https://a1000.example.com/api/samples/v2/list/' \
  --header 'Authorization: Token exampletoken' \
  --header 'Content-Type: application/json' \
  --data '{"hash_values":["0da28a5159bee9cd930403023230f2e918b0334d"], "fields": ["summary"]}'
```

**Python**

```python

# Change the token
token = "exampletoken"
# Change the hostname in the URL
url = f"https://appliance.example.com/api/samples/v2/list/"

json = {
        "hash_values": ["examplehash1", "examplehash2"],
        "fields": ["sha256", "extracted_file_count"]
}

headers = {'Authorization': f'Token {token}'}

# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.post(url, headers=headers, json=json)
print(response.text)
```

### Response Format

**Response Examples**

Default response - all available fields

```json
{
   "count": 1,
   "next": null,
   "previous": null,
   "results": [
      {
            "id": 215590,
            "sha1": "3ecb56536b58d2e2ec0779d1c28a9f20024d6b66",
            "sha256": "eac444d6cddbae6972f0af91da5a89b0eb370c2f7bbe6f9706aaaf1f25f6c0d3",
            "sha512": "5586169dc50e339789b75f469e3 (...)",
            "md5": "6cadcefb80b7e757323aa46fba909d72",
            "imphash": "9612c82b4c865e0bf6797463aa91292a",
            "category": "application",
            "file_type": "PE",
            "file_subtype": "Exe",
            "identification_name": "UPX",
            "identification_version": "0.60-3.x",
            "file_size": 350720,
            "extracted_file_count": 9,
            "local_first_seen": "2017-02-06T18:10:54.594306Z",
            "local_last_seen": "2020-02-27T11:37:37.954472Z",
            "classification_origin": {
               "sha1": "8d0cbc4f10b2aa40f849bda9ee2524146870cc7a",
               "sha256": "cc8698fac45061e5bb1a2cc712d25c5ed5977f3b5b5cc55978562df942777815",
               "sha512": "96bf5eba3dfd04a5bccaeb45 (...)",
               "md5": "cf87a4c0f97ef995221650b4c8116e04",
               "imphash": "fe93401dae4bdb92076a6adf424ffc73"
            },
            "classification_reason": "cloud",
            "classification": "malicious",
            "riskscore": 8,
            "classification_result": "Win32.Backdoor.Prorat",
            "tags": {
               "ticore": [
                  "yara",
                  "indicator-network",
                  "string-http",
                  "capability-execution",
                  "capability-filesystem",
                  "capability-networking",
                  "desktop",
                  "indicator-execution",
                  "indicator-monitor",
                  "arch-x86",
                  "gui",
                  "packed",
                  "entropy-high",
                  "contains-pe",
                  "file-download",
                  "privacy-intrusion",
                  "ftp-use",
                  "compression-nrv",
                  "cloud"
               ],
               "user": [
                  "RSA2016",
                  "testtag1"
               ]
            }
      }
   ]
}
```

Response for the optional `summary` field

```json
{
   "count": 1,
   "next": null,
   "previous": null,
   "results": [
      {
         "summary": {
            "id": 215600,
            "sha1": "0da28a5159bee9cd930403023230f2e918b0334d",
            "indicators": [
               {
                     "priority": 7,
                     "category": 22,
                     "description": "Deletes files in Windows system directories."
               },
               {
                     "priority": 7,
                     "category": 11,
                     "description": "Requests permission required to shut down a system."
               }
            ],
            "unpacking_status": {
               "failed": 0,
               "success": 1,
               "partial": 0
            }
         }
      }
   ]
}
```

**Response Fields**

| FIELD NAME                | TYPE                                                         |
| :------------------------ | :----------------------------------------------------------- |
| id                        | integer                                                      |
| sha1                      | string                                                       |
| sha256                    | string                                                       |
| md5                       | string                                                       |
| category                  | string                                                       |
| file_type                 | string                                                       |
| file_subtype              | string                                                       |
| identification_name       | string                                                       |
| identification_version    | string                                                       |
| file_size                 | integer                                                      |
| extracted_file_count      | integer                                                      |
| local_first_seen          | string                                                       |
| local_last_seen           | string                                                       |
| classification_origin     | object                                                       |
| classification_reason     | string                                                       |
| classification            | string                                                       |
| riskscore                 | integer                                                      |
| classification_result     | string                                                       |
| tags                      | array                                                        |
| aliases                   | array                                                        |
| summary                   | *Summary* object                                             |
| ticore                    | corresponds to the `ticore` object from the [Spectra Core Report API](./static-analysis-report-api.md) |
| ticloud                   | *Cloud* object                                               |
| imphash                   | string                                                       |
| classification_source     | integer                                                      |
| discussion                | array                                                        |
| proposed_filename         | string                                                       |
| networkthreatintelligence | object                                                       |
| domainthreatintelligence  | object                                                       |
| av_scanners               | object                                                       |
| av_scanners_summary       | object                                                       |

| FIELD NAME | DATA TYPE |
| :--------- | :-------- |
| sha1       | string    |
| sha256     | string    |
| sha512     | string    |
| md5        | string    |
| imphash    | string    |

| FIELD NAME       | DATA TYPE           |
| :--------------- | :------------------ |
| id               | integer (sample id) |
| sha1             | string              |
| indicators       | array               |
| unpacking_status | string              |

| FIELD NAME            | DATA TYPE |
| :-------------------- | :-------- |
| classification        | string    |
| riskscore             | integer   |
| classification_result | string    |
| classification_reason | string    |
| first_seen            | string    |
| last_seen             | string    |

**Response Status Codes**

| CODE | DESCRIPTION                                                  |
| :--- | :----------------------------------------------------------- |
| 200  | Returned on successful requests.                             |
| 400  | Malformed hash or invalid field name.                        |
| 403  | Authentication credentials were not provided. / Invalid token. |
| 404  | Malformed endpoint.                                          |
