# List events

Fetches events for System Admin users. This includes actions such as creating, updating, loading, deleting, and more of items such as sheets, reports, dashboards, attachments, and users in your Smartsheet organization account.

See Event types for the complete event listing, details, and example objects.

> Who can use this operation?
> 
> - Plans: Requires the Event Reporting premium add-on available for Enterprise and Advanced Work Management plans only.
> - Permissions: System Admin

> Note: You must specify exactly one of the query parameters since or streamPosition. Both are optional individually, but one is required.

Endpoint: GET /events
Version: 2.0.0
Security: APIToken, OAuth2

## Header parameters:

  - `smartsheet-integration-source` (string)
    Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

- Integration source type
- Organization name
- Integration source name 

Format:


TYPE,OrgName,SourceName


Examples: 

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater
    Example: "AI,SampleOrg,My-AI-Connector-v2"

  - `Accept-Encoding` (string)
    Strongly recommended to make sure payload is compressed. Must be set to one of the following values:
* deflate
* gzip
    Enum: "deflate", "gzip"

  - `Authorization` (string)
    API Access Token used to authenticate requests to Smartsheet APIs.

## Query parameters:

  - `since` (string)
    The earliest time from which events are included in the response. Events before this time are excluded.

This parameter is required if streamPosition is not used.

The date-time value is resolved to the nearest hour. The value is interpreted as ISO-8601 format, unless numericDates is specified (see details about numericDates below).

Important: To keep event responses manageable and prevent timeouts, also specify the to query parameter.

Important: This parameter is intended for use when backfilling data at client startup or recovery--don't use it for fine-grained, date-based queries.

  - `to` (string)
    The latest time up to which events are included in the response. Events after this time are excluded.

This parameter requires using the since parameter. 

The date-time value is resolved to the nearest hour. The value is interpreted as ISO-8601 format, unless numericDates is specified (see details about numericDates below).

Logic:

- If to is a future time, the current time is used.
- If to equals the since time, an empty data value is returned.
- If to is before the since time, a validation error is returned.

Important: This parameter is intended for use when backfilling data at client startup or recovery--don't use it for fine-grained, date-based queries.

  - `streamPosition` (string)
    Indicates next set of events to return. Use value of
nextStreamPosition returned from the previous call.

This parameter is required if since is not used.
    Example: "XyzAb1234cdefghijklmnofpq"

  - `maxCount` (integer)
    Maximum number of events to return as response to this call.
Must be between 1 through 10,000 (inclusive).
Defaults to 1,000 if not specified.

  - `numericDates` (boolean)
    If true, dates are accepted and returned in Unix epoch time
(milliseconds since midnight on January 1, 1970 in UTC time).

Default is false, which means ISO-8601 format.

  - `managedPlanId` (number)
    The target managed plan for which to list events. Authorized if the
caller is a system administrator on either the target managed plan or
the main plan in EPM hierarchy.

## Response 200 fields (application/json):

  - `nextStreamPosition` (string)
    This string should be passed back to the next GET events call to obtain
subsequent events.
    Example: "XyzAb1234cdefghijklmnofpq"

  - `moreAvailable` (boolean)
    True if more results are available. This is typically due to event counts
exceeding the maxCount parameter passed in.
    Example: true

  - `data` (array)
    List of Events

## Response 400 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 401 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 403 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 404 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 405 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 406 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 410 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 415 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 429 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 500 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.