Skip to main content
GET
/
events
cURL
curl -i -X GET "https://api.box.com/2.0/events" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
{
  "chunk_size": 2,
  "next_stream_position": "1152922976252290886",
  "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": "[email protected]"
      },
      "event_type": "FILE_MARKED_MALICIOUS",
      "session_id": "70090280850c8d2a1933c1",
      "source": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "[email protected]",
        "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": "[email protected]",
          "is_confirmed": true
        }
      },
      "additional_details": {
        "key": "value"
      }
    }
  ]
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
stream_type
enum<string>
default: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.
Available options:
all,
changes,
sync,
admin_logs,
admin_logs_streaming
​
stream_position
string

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.
​
limit
integer<int64>
default:100

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.

Required range: x <= 500
​
event_type
enum<string>[]

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.

An event type that can be filtered by.

Available options:
ACCESS_GRANTED,
ACCESS_REVOKED,
ADD_DEVICE_ASSOCIATION,
ADD_LOGIN_ACTIVITY_DEVICE,
ADMIN_LOGIN,
APPLICATION_CREATED,
APPLICATION_PUBLIC_KEY_ADDED,
APPLICATION_PUBLIC_KEY_DELETED,
CHANGE_ADMIN_ROLE,
CHANGE_FOLDER_PERMISSION,
COLLABORATION_ACCEPT,
COLLABORATION_EXPIRATION,
COLLABORATION_INVITE,
COLLABORATION_REMOVE,
COLLABORATION_ROLE_CHANGE,
COMMENT_CREATE,
COMMENT_DELETE,
CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY,
CONTENT_WORKFLOW_AUTOMATION_ADD,
CONTENT_WORKFLOW_AUTOMATION_DELETE,
CONTENT_WORKFLOW_POLICY_ADD,
CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION,
CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION,
COPY,
DATA_RETENTION_CREATE_RETENTION,
DATA_RETENTION_REMOVE_RETENTION,
DELETE,
DELETE_USER,
DEVICE_TRUST_CHECK_FAILED,
DOWNLOAD,
EDIT,
EDIT_USER,
EMAIL_ALIAS_CONFIRM,
EMAIL_ALIAS_REMOVE,
ENTERPRISE_APP_AUTHORIZATION_UPDATE,
EXTERNAL_COLLAB_SECURITY_SETTINGS,
FAILED_LOGIN,
FILE_MARKED_MALICIOUS,
FILE_WATERMARKED_DOWNLOAD,
GROUP_ADD_ITEM,
GROUP_ADD_USER,
GROUP_CREATION,
GROUP_DELETION,
GROUP_EDITED,
GROUP_REMOVE_ITEM,
GROUP_REMOVE_USER,
ITEM_EMAIL_SEND,
ITEM_MODIFY,
ITEM_OPEN,
ITEM_SHARED_UPDATE,
ITEM_SYNC,
ITEM_UNSYNC,
LEGAL_HOLD_ASSIGNMENT_CREATE,
LEGAL_HOLD_ASSIGNMENT_DELETE,
LEGAL_HOLD_POLICY_CREATE,
LEGAL_HOLD_POLICY_DELETE,
LEGAL_HOLD_POLICY_UPDATE,
LOCK,
LOGIN,
METADATA_INSTANCE_CREATE,
METADATA_INSTANCE_DELETE,
METADATA_INSTANCE_UPDATE,
METADATA_TEMPLATE_CREATE,
METADATA_TEMPLATE_DELETE,
METADATA_TEMPLATE_UPDATE,
MOVE,
NEW_USER,
OAUTH2_ACCESS_TOKEN_REVOKE,
PREVIEW,
REMOVE_DEVICE_ASSOCIATION,
REMOVE_LOGIN_ACTIVITY_DEVICE,
RENAME,
RETENTION_POLICY_ASSIGNMENT_ADD,
SHARE,
SHARED_LINK_SEND,
SHARE_EXPIRATION,
SHIELD_ALERT,
SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED,
SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION,
SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED,
SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION,
SHIELD_JUSTIFICATION_APPROVAL,
SHIELD_SHARED_LINK_ACCESS_BLOCKED,
SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE,
SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE,
SIGN_DOCUMENT_ASSIGNED,
SIGN_DOCUMENT_CANCELLED,
SIGN_DOCUMENT_COMPLETED,
SIGN_DOCUMENT_CONVERTED,
SIGN_DOCUMENT_CREATED,
SIGN_DOCUMENT_DECLINED,
SIGN_DOCUMENT_EXPIRED,
SIGN_DOCUMENT_SIGNED,
SIGN_DOCUMENT_VIEWED_BY_SIGNED,
SIGNER_DOWNLOADED,
SIGNER_FORWARDED,
STORAGE_EXPIRATION,
TASK_ASSIGNMENT_CREATE,
TASK_ASSIGNMENT_DELETE,
TASK_ASSIGNMENT_UPDATE,
TASK_CREATE,
TASK_UPDATE,
TERMS_OF_SERVICE_ACCEPT,
TERMS_OF_SERVICE_REJECT,
UNDELETE,
UNLOCK,
UNSHARE,
UPDATE_COLLABORATION_EXPIRATION,
UPDATE_SHARE_EXPIRATION,
UPLOAD,
USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE,
WATERMARK_LABEL_CREATE,
WATERMARK_LABEL_DELETE
​
created_after
string<date-time>

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>

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.

Response

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.

A list of event objects.

​
chunk_size
integer<int64>

The number of events returned in this response.

Example:

2

​
next_stream_position

The stream position of the start of the next page (chunk) of events.

Example:

"1152922976252290886"

​
entries
Event · object[]

A list of events.