# Events

Events document an action taken by a user in the system. They provide metadata about the action and a string representation suitable for display. You can **list** all events for a user or a file.

## List all Events for a User

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/activity/`

List all events for a user across all of their Workspaces.

#### Request Body

| Name         | Type    | Description                                                                                                                                                       |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspaces   | array   | The id of the Workspace(s) to list events for as an array of integers.                                                                                            |
| verbs        | array   | The action(s) taken in the events. Available verbs are create, upload, read, download, update, delete, and invite.                                                |
| filter\_self | boolean | Should the users' own events be removed? Defaults to false.                                                                                                       |
| actor        | integer | The id of the user to list events for.                                                                                                                            |
| start\_time  | string  | The earliest time you would like to see events from. Timestamps should be specified in RFC-2822 format and will assume the same time zone as the requesting user. |
| end\_time    | string  | The latest time you would like to see events from. Timestamps should be specified in RFC-2822 format and will assume the same time zone as the requesting user.   |

{% tabs %}
{% tab title="200 Returns a paginated array of event objects and a 200 if the call succeeds." %}

```yaml
{
  "total_entries": 0,
  "current_page": 1,
  "total_pages": 0,
  "per_page": 30,
  "items": [
    {
      "event": {
        "id": 5063247,
        "updated_at": "2016-01-18T11:16:53-08:00",
        "detail": "<subject>Matthew Anderson</subject> <predicate>viewed</predicate> the <object><a href=\"/workspaces/4137/files/849607\">onehub-logo.png</a> File</object> <complement>(7 KB)</complement> in the <object><a href=\"/workspaces/4137\">Testing the API</a> Workspace</object>",
        "workspace_id": 4137,
        "user_id": 481
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## List all Events for a File

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/files/:id/audit_trail`

Lists all events for the file specified via `:id`. This resource is only available to users with a role of **Moderator** or above.

#### Path Parameters

| Name | Type    | Description                                                          |
| ---- | ------- | -------------------------------------------------------------------- |
| :id  | integer | The unique identifier of the file you would like to list events for. |

{% tabs %}
{% tab title="200 Returns a paginated array of event objects and a 200 if the call succeeds." %}

```yaml
{
  "total_entries": 1,
  "current_page": 1,
  "total_pages": 1,
  "per_page": 30,
  "items": [
    {
      "event": {
        "id": 5062927,
        "updated_at": "2016-01-15T16:22:45-08:00",
        "detail": "<subject>Matthew Anderson</subject> <predicate>uploaded</predicate> the <object><a href=\"/workspaces/4137/files/849607\">Onehub_Med_RGB.png</a> File</object> <complement>(7 KB)</complement> to the <object><a href=\"/workspaces/4137\">Testing the API</a> Workspace</object>",
        "workspace_id": 4137,
        "user_id": 481
      }
    }
  ]
}
```

{% endtab %}

{% tab title="403 Returns a 403 with an error in the message body if the user has a role lower than Moderator in the specified Workspace." %}

```yaml
//
```

{% endtab %}
{% endtabs %}