Box Developer Documentation

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

Register now!

Get User Events

Get User Events

To get a user's events, authenticate as any user and make a call to the GET /events API.

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);

The events returned will only be for the user who's access token the API was made with. To get the event feed for a different user either use the as-user header or an actual access token for that user.

Stream Types

The user event stream support 3 types of stream.

Stream Type
allReturns everything for a user (default)
changesReturns events that may cause file tree changes such as file updates or collaborations.
syncIs similar to changes but only applies to synced folders

Anonymous Users

In some cases, the event feed might list a user with an ID of 2. This is Box's internal identifier for anonymous users.

An anonymous user is a user that is not logged in. This can happen any time a user interacts with content and they aren't asked to log in first. An example would be when a user downloads a file through an open shared link.

Limitations

Box does not store events indefinitely.

User events are stored for between two weeks and two months, after which the user events are removed. Enterprise events are accessible for one year via the API and seven years via exported reports in the Box Admin Console.

The emphasis of this feed is to return the complete results quickly, which means that Box may return events more than once or out of order. Duplicate events can be identified by their event IDs.

Long Polling

The user event stream supports long-polling through the OPTIONS /events API.

Event Types

The following events can be triggered for a user. This list is not exhaustive, so it is possible events appear that are not listed.

The following events are available in all feeds.

Event nameDescription
ITEM_CREATEA folder or File was created
ITEM_UPLOADA folder or File was uploaded
ITEM_MOVEA file or folder was moved
ITEM_COPYA file or folder was copied
LOCK_CREATEA file was locked
LOCK_DESTROYA file was unlocked. If a locked file is deleted, the source file will be null.
ITEM_TRASHA file or folder was marked as deleted
ITEM_UNDELETE_VIA_TRASHA file or folder was recovered out of the trash
COLLAB_ADD_COLLABORATORA collaborator was added to a folder
COLLAB_ROLE_CHANGEA collaborator had their role changed
COLLAB_INVITE_COLLABORATORA collaborator was invited on a folder
COLLAB_REMOVE_COLLABORATORA collaborator was removed from a folder
ITEM_SYNCA folder was marked for sync
ITEM_UNSYNCA folder was unmarked for sync
ITEM_RENAMEA file or folder was renamed
ITEM_MAKE_CURRENT_VERSIONA previous version of a file was promoted to the current version
GROUP_ADD_USERAdded user to group
GROUP_REMOVE_USERRemoved user from group

The following events are only available in the all feed.

Event nameDescription
COMMENT_CREATEA comment was created on a folder, file, or other comment
COMMENT_DELETEA comment was deleted on folder, file, or other comment
ITEM_DOWNLOADA file or folder was downloaded
ITEM_PREVIEWA file was previewed
TASK_ASSIGNMENT_CREATEA task was assigned
TASK_CREATEA task was created
ITEM_SHARED_CREATEA file or folder was enabled for sharing
ITEM_SHARED_UNSHAREA file or folder was disabled for sharing
ITEM_SHAREDA folder was shared
TAG_ITEM_CREATEA Tag was added to a file or folder
ENABLE_TWO_FACTOR_AUTH2 factor authentication enabled by user.
MASTER_INVITE_ACCEPTFree user accepts invitation to become a managed user.
MASTER_INVITE_REJECTFree user rejects invitation to become a managed user.
ACCESS_GRANTEDGranted Box access to account.
ACCESS_REVOKEDRevoke Box access to account.