Join BoxWorks 2024 to discover what's possible with content and AI!

List user and enterprise events

get

https://api.box.com/2.0

/events

Returns up to a year of past events for a given user or for the entire enterprise.

By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the stream_type to admin_logs_streaming for live monitoring of new events, or admin_logs for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope manage enterprise properties checked.

Related Guides

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Query Parameters

created_after string (date-time)in queryoptional

example2012-12-12T10:53:43-08:00

The lower bound date and time to return events for. This can only be used when requesting the events with a stream_type of admin_logs. For any other stream_type this value will be ignored.

created_before string (date-time)in queryoptional

example2013-12-12T10:53:43-08:00

The upper bound date and time to return events for. This can only be used when requesting the events with a stream_type of admin_logs. For any other stream_type this value will be ignored.

event_type string arrayin queryoptional

exampleACCESS_GRANTED

A comma-separated list of events to filter by. This can only be used when requesting the events with a stream_type of admin_logs or adming_logs_streaming. For any other stream_type this value will be ignored.

limit integer (int64)in queryoptional

example50default100max500

Limits the number of events returned

Note: Sometimes, the events less than the limit requested can be returned even when there may be more events remaining. This is primarily done in the case where a number of events have already been retrieved and these retrieved events are returned rather than delaying for an unknown amount of time to see if there are any more results.

stream_position stringin queryoptional

example1348790499819

The location in the event stream to start receiving events from.

now will return an empty list events and the latest stream position for initialization.
0 or null will return all events.

stream_type stringin queryoptional

examplealldefault"all"

Defines the type of events that are returned

all returns everything for a user and is the default
changes returns events that may cause file tree changes such as file updates or collaborations.
sync is similar to changes but only applies to synced folders
admin_logs returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for programmatically pulling from a 1 year history of events across all users within the enterprise and within a created_after and created_before time frame. The complete history of events will be returned in chronological order based on the event time, but latency will be much higher than admin_logs_streaming.
admin_logs_streaming returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for polling for recent events across all users within the enterprise. Latency will be much lower than admin_logs, but events will not be returned in chronological order and may contain duplicates.

Value is one of all,changes,sync,admin_logs,admin_logs_streaming

Response

200application/jsonEvents

Returns a list of event objects.

Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a chunk_size parameter indicating how many events were returned in this chunk, as well as the next stream_position that can be queried.

defaultapplication/jsonClient error

An unexpected client error.

get

List user and enterprise events

You can now try out some of our APIs live, right here in the documentation.

Request Example

cURL

curl -i -X GET "https://api.box.com/2.0/events" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

TypeScript Gen

await client.events.getEvents({
  streamType: 'admin_logs' as GetEventsQueryParamsStreamTypeField,
  limit: 1,
  createdAfter: createdAfterDate,
  createdBefore: createdBeforeDate,
} satisfies GetEventsQueryParams);

Python Gen

client.events.get_events(
    stream_type=GetEventsStreamType.ADMIN_LOGS.value,
    limit=1,
    created_after=created_after_date,
    created_before=created_before_date,
)

.NET Gen

await client.Events.GetEventsAsync(queryParams: new GetEventsQueryParams() { StreamType = GetEventsQueryParamsStreamTypeField.AdminLogs, Limit = 1, CreatedAfter = createdAfterDate, CreatedBefore = createdBeforeDate });

Java

EventStream stream = new EventStream(api);
stream.addListener(new EventListener() {
  public void onEvent(BoxEvent event) {
      // Handle the event.
    }
});
stream.start();

Python

stream_position = 0
events = client.events().get_events(stream_position=stream_position)
stream_position = events['next_stream_position']
for event in events['entries']:
    print(f'Got {event.event_type} event that occurred at {event.created_at}')

.NET

BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.UserEventsAsync();

Node

client.events.get({stream_position: '1408838928446360'}, callback);

Response Example

{
  "chunk_size": 2,
  "entries": [
    {
      "type": "event",
      "created_at": "2022-12-12T10:53:43-08:00",
      "recorded_at": "2022-12-12T10:54:43-08:00",
      "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "event_type": "FILE_MARKED_MALICIOUS",
      "session_id": "70090280850c8d2a1933c1",
      "source": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "language": "en",
        "timezone": "Africa/Bujumbura",
        "space_amount": 11345156112,
        "space_used": 1237009912,
        "max_upload_size": 2147483648,
        "status": "active",
        "job_title": "CEO",
        "phone": "6509241374",
        "address": "900 Jefferson Ave, Redwood City, CA 94063",
        "avatar_url": "https://www.box.com/api/avatar/large/181216415",
        "notification_email": {
          "email": "notifications@example.com",
          "is_confirmed": true
        }
      },
      "additional_details": {
        "key": "value"
      }
    }
  ],
  "next_stream_position": 1152922976252290800
}