# Advanced Search API — Query Samples on Spectra Analyze

> Search samples on Spectra Analyze and Spectra Intelligence using field queries, pagination, and sorting. POST /api/samples/v3/search/ endpoint reference.

```
POST /api/samples/v3/search/
```

## Search for samples

Search for samples available on the local Spectra Analyze instance and Spectra Intelligence using the Advanced Search capabilities. Users can authenticate with their regular [Spectra Analyze tokens](./tokens.md).

- All [restricted words and characters](../advanced-search.md#restricted-words-and-characters) must be escaped with double quotation marks.
- All datetime fields are in UTC format: YYYY-MM-DDThh:mm:ssZ.
- The default and only supported response format is JSON.
- Requests must contain the HTTP header field with *Content-­Type: application/json*.
- By default, the API returns 20 samples per page.

### Request Format

```json
{
   "query": "<field_name>:<field_value> <field_name>:<field_value> ...",
   "page": 1,
   "records_per_page": 20,
   "sort": "<field_name> desc"
}
```

**Request Parameters**

| NAME              | DESCRIPTION                                                  | REQUIRED                                |
| :---------------- | :----------------------------------------------------------- | :-------------------------------------- |
| query             | String representing the search expression.                   | Yes                                     |
| ticloud           | Show only cloud results in the response. This parameter is false by default. If omitted, the response will show only local results. | No                                      |
| page              | If more than ``<records_per_page>`` records match the requested criteria, the response will have a next_page value, which can be used in the request to fetch the next page with up to ``<records_per_page>`` results. This is the value defining which page of results to return in the response. Defaults to first page (1) if omitted. | No                                      |
| records_per_page  | Value defining how many results should be returned per page. Defaults to 20 if omitted. Maximum value is 100. | No                                      |
| sort              | String that allows sorting the results by one of the supported fields: **sha1**, **firstseen**, **threatname**, **sampletype**, **filecount**, **size**. The results can be sorted in ascending or descending order by using the *asc* or *desc* keywords. By default, the results are sorted by **firstseen** in descending order (most recent to oldest). | No                                      |
| start_search_date | The starting date for the search. This parameter represents the later date, as searches are performed backwards in time. | Only used if `ticloud` is set to `true` |
| end_search_date   | The ending date for the search. This parameter represents the earlier date, as searches are performed backwards in time. | Only used if `ticloud` is set to `true` |

### Using time range parameters

Both time range parameters should be formatted as strings in the “YYYY-MM-DD” format. For further granularity, the `firstseen` keyword can be used to specify a particular time of day.

Search queries progress backward in time, meaning that results are first returned closer to the `end_search_date`. Both `start_search_date` and `end_search_date` are included in the search, allowing the query to return results for both dates, if available.

It is possible that the query only returns results until some point in time, instead of for the whole given time range. In that case, the `last_search_date` parameter will be returned, which can be used as `end_search_date` in the next query.

**Note:** The **last_search_date** is not included in search.

When the `end_of_dataset` parameter is returned in the response, it means that the query found all samples which meet the search criteria in the given time range. This parameter applies only to Cloud searches, and should be ignored in local queries.

### Advanced Search Queries

The *query* field contains the search expression that will be submitted to the API. Every search expression must contain at least one keyword and one value.

Search expressions are built according to the following formula: ``<field_name>:<field_value>``.

Supported values for *field_name* correspond to [keywords currently supported by Advanced Search](../advanced-search.md#supported-search-keywords).

For *field_value*, the following are supported:

- equals operator - to search for exact matches (classification:malicious, available:true…)
- range operator - to search for closed ranges of values, including the upper and lower boundary (firstseen:[2018-01-01T00:00:00Z TO 2018-01-02T00:00:00Z]) or open-ended ranges indicating greater/less-than values (threatlevel:[0 TO *])
- in operator - to search for any value in the specified list (classification:[malicious, suspicious])
- [wildcard symbols](../advanced-search.md#using-wildcards-for-partial-matching) - for search keywords that support them (av-detection:*crypto)

It is also possible to use [operators and multi-keyword combinations](../advanced-search.md#creating-multi-keyword-search-queries).

**Search Query Example**

```json
{
   "query": "firstseen:2018-01-01T00:00:00Z (av-detection:trojan AND type:binary NOT positives:[* TO 3])"
}
```

### Request Examples

Format of the POST request body:

```json
{
   "query":"classification:[malicious, suspicious]",
   "records_per_page":10,
   "start_search_date":"2023-01-01",
   "end_search_date":"2023-07-01",
   "ticloud":True
}
```

`Query` contains all the keywords related to the sample, while the other fields specify the format of the response.

**cURL**

```bash
# Add --insecure before the URL if you're using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/samples/v3/search/' \
--header 'Authorization: Token exampletoken' \
--header 'Content-Type: application/json' \
--data '{"query":"classification:[malicious, suspicious]","records_per_page":10,"start_search_date":"2023-01-01","end_search_date":"2023-07-01","ticloud":True}'
```

**Python**

```python

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

json = {"query":"classification:[malicious, suspicious]","records_per_page":10,"start_search_date":"2023-01-01","end_search_date":"2023-07-01","ticloud":True}

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

```json
{
   "rl":{
      "web_search_api":{
         "next_page":2,
         "more_pages":true,
         "sample_count":10,
         "entries":[
            {
               "sha1":"465aa6e49e02cd677924a6c4486f82f53a6a90f1",
               "sha256":"92fdba6367ea91001515b3b1a0a47892fb04a3606fe7c339a95431ea71467c43",
               "md5":"d35bd156250608f3a182fe75a72cd032",
               "filename":"_00145",
               "antivirus":28,
               "firstseen":"2023-07-01T23:59:59Z",
               "lastseen":"2023-07-04T08:05:19Z",
               "available":true,
               "size":52175,
               "sampletype":"PE/Exe",
               "classification":"malicious",
               "threatname":"Win32.Worm.Eggnog",
               "factor":10,
               "filecount":0
            },
            "..."
         ],
         "last_search_date":"2023-06-30",
         "end_of_dataset":false
      }
   }
}
```

If the ticloud parameter is set and the available field is true, the sample is shareable in the Spectra Intelligence cloud, but if it is false, the sample is private.

The `total_count` field will be returned only if `"ticloud"=false`. Total sample count for Spectra Intelligence data must be retrieved with the Total Count endpoint documented below.

**Response Status Codes**

| CODE | DESCRIPTION                                                  |
| :--- | :----------------------------------------------------------- |
| 200  | OK                                                           |
| 400  | Bad request. E.g. invalid value for a field, or other validation error. |
| 403  | Forbidden. This response is returned when the request isn’t authenticated. |
| 404  | Not found. E.g. wrong URL.                                   |

## Total Count

```
POST /api/samples/v3/search/total-count
```

This endpoint returns total counts for samples present in the Spectra Intelligence cloud. It always behaves as if the `ticloud` parameter is set to `true`.

Total counts for local samples are returned in regular search query responses as the `total_count` field, if `ticloud=false`.

It supports single queries and follows the same rules as the search query endpoint.

Bulk queries return response code 400 with the message “Bulk query not supported on total count endpoint”.

Since the total count query goes backwards in time, it is possible that the `total_count` query only returns count until some point in time, instead of for the whole given time range. In that case, the `last_search_date` parameter will be returned, which can be used as `end_search_date` in the next query.

Note: **last_search_date** is not included in the count.

**Request Format**

```
{
   "query": "<field_name>:<field_value> <field_name>:<field_value> ...",
   "start_search_date": "YYYY-MM-DD",
   "end_search_date": "YYYY-MM-DD"
}
```

**Request Parameters**

| NAME              | DESCRIPTION                                                  | REQUIRED |
| :---------------- | :----------------------------------------------------------- | :------- |
| query             | String representing the search expression. Refer to the Advanced Search endpoint documentation above for more information. | Yes      |
| start_search_date | The starting date for the search. This parameter represents the later date, as searches are performed backwards in time. | Yes      |
| end_search_date   | The ending date for the search. This parameter represents the earlier date, as searches are performed backwards in time. | Yes      |

### Request Examples

```json
{
   "query":"classification:[malicious, suspicious]",
   "start_search_date":"2023-01-01",
   "end_search_date":"2023-07-01",
}
```

#### Response Format

```json
{
"total_count": 1510377,
"last_search_date": "2023-06-30",
"end_of_dataset": false
}
```
