# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.onehub.com/methods/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.