GET/events

List user and enterprise 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.

6 parameters

stream_typestringoptional

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.

Allowed:allchangessyncadmin_logsadmin_logs_streamingDefault:all

stream_positionstringoptional

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.

limitintegeroptional

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.

Default:100

event_typearray<string>optional

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.

created_afterstringoptional

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_beforestringoptional

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.

2 status codes

200Returns 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.

chunk_sizeintegeroptional

The number of events returned in this response.

next_stream_positionstringoptional

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

entriesarray<Event>optional

A list of events.

defaultAn unexpected client error.

typestringoptional

The value will always be `error`.

Allowed:error

statusintegeroptional

The HTTP status of the response.

codestringoptional

A Box-specific error code.

Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed

messagestringoptional

A short message describing the error.

context_infoobjectoptional

A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.

help_urlstringoptional

A URL that links to more information about why this error occurred.

request_idstringoptional

A unique identifier for this response, which can be used when contacting Box support.

Error handling

Any other status is an error: An unexpected client error.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
});

const result = await client.events.list({
  streamType: "example",
  streamPosition: "example",
  limit: 20,
  eventType: "example",
  createdAfter: "example",
});

{
  "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": "ceo@example.com"
      },
      "event_type": "example_value",
      "session_id": "70090280850c8d2a1933c1",
      "source": {
        "created_at": null,
        "modified_at": null,
        "language": null,
        "timezone": null,
        "space_amount": null,
        "space_used": null,
        "max_upload_size": null,
        "status": null,
        "job_title": null,
        "phone": null,
        "address": null,
        "avatar_url": null,
        "notification_email": null
      },
      "additional_details": {
        "key": "value"
      }
    }
  ]
}

Request

Response

Errors