> For the complete documentation index, see [llms.txt](https://developers.couchdrop.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.couchdrop.io/administration/auditing-and-reporting.md).

# Auditing and Reporting

## Get audit events

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/files`

#### Query Parameters

| Name     | Type   | Description        |
| -------- | ------ | ------------------ |
| page     | Number | Page number        |
| pagesize | Number | Required page size |

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API token   |

#### Request Body

| Name      | Type    | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| transfers | Boolean | Example filter. See filters below for more details of available filters |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "files":[{
        "time":<timestamp>,    
        "filename":"",
        "filename_relative":"",
        "authenticated_user":"",
        "event_type":"", 
        "success":true,
        "total_size":0,
        "additional_info": "",
        "message": "a message"
    }],
    "pagination":{
        "total_records": total_records,
        "page": page,
        "page_size": pagesize,
        "total_pages": total_pages
    }
}
```

{% endtab %}
{% endtabs %}

#### Complex Filters

The API allows you to filter and search for specific events and event types. Filters are supplied as POST body params in JSON.&#x20;

| Filter Param        | Description                                                                 | Example value     |
| ------------------- | --------------------------------------------------------------------------- | ----------------- |
| transfers           | Include UPLOAD and DOWNLOAD events                                          | true              |
| authentication      | Include authentication events.                                              | true              |
| malware             | Include malware events                                                      | true              |
| admin               | Include admin and management events                                         | true              |
| filesystem          | Include filesystem events like LS/LSTAT/RENAME                              | true              |
| workflow            | Include workflow events                                                     | true              |
| authenticated\_user | Filter events to a specific user                                            | "user1"           |
| transaction\_id     | Filter events to a specific transaction id                                  | "\<uuid>"         |
| filename            | Filter events to a specific filename                                        | "example.txt"     |
| search              | Wildcard search on the filename and message field                           | "downloaded file" |
| workflow\_id        | Filter events to those to those generated by a specific workflow/automation | "\<uuid>"         |

#### Specifying a time frame filter&#x20;

You can restrict results to a specific time period, this can be done using relative or absolute time. Time filtering is sent to the API in the same way as the [#complex-filters](#complex-filters "mention") above.&#x20;

| Filter param        | Description                                                                   | Example                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| date                | Filter type                                                                   | <p>Accepted values: </p><ul><li>hour</li><li>2hours</li><li>day</li><li>week</li><li>month</li><li>custom</li></ul> |
| custom\_start\_date | When "date" is set to "custom" this is required. A unix timestamp is required | 1674767806                                                                                                          |
| custom\_end\_date   | End date for above                                                            | 1674769100                                                                                                          |