# List filtered events

Fetches events related to given sheets and workspaces for non-admin users.

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: Non-admin users who have access to given sheets or workspaces.

Endpoint: POST /filteredEvents
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.

## Request fields (application/json):

  - `sheetIds` (array)
    Array of sheet Ids used to filter events. Only events related to the specified sheet Ids are returned.

  - `workspaceIds` (array)
    Array of workspace Ids used to filter events. Only events related to the specified workspace Ids are returned.

  - `since` (string)
    The earliest time from which events are included in the response. Events before this time are excluded. This field is intended for use when backfilling data at client startup or recovery--don't use it for fine-grained date-based queries. Therefore, resolution is limited to the nearest hour. The value is interpreted as ISO-8601 format, unless numericDates is specified (see details about numericDates below).

You must pass in a value for either since or streamPosition and never both.

  - `to` (string)
    The latest time up to which events are included in the response. Events after this time are excluded. The to field requires using the since body field (above). This field is intended for use when backfilling data at client startup or recovery--don't use it for fine-grained date-based queries. Therefore, resolution is limited to the nearest hour. The value is interpreted as ISO-8601 format, unless numericDates is specified (see details about numericDates below).

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, an error is returned.

  - `streamPosition` (string)
    Indicates next set of events to return. Use value of nextStreamPosition returned from the previous call.
You must pass in a value for either since or streamPosition and never both.
    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 licensed user 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

  - `data.eventId` (string)
    Unique event identifier.
    Example: "2.1.iI9WIpaEAhjz-0hV0eGw2lOEoKDqoRUP00NJv2RvAyKoOvyws63zsfpTBqda5tb33ylcz2JdGVC9Rfa2FRJKQg"

  - `data.objectType` (string)
    The type of Smartsheet resource object impacted by the event.

See [Event types](/api/smartsheet/event-types) for all the event object types.
    Example: "SHEET"

  - `data.action` (string)
    The action applied to the specified object, such as CREATE, UPDATE, or DELETE.

See [Event types](/api/smartsheet/event-types) for actions associated with each event object type.
    Example: "UPDATE"

  - `data.objectId` (string)
    The identifier of the object impacted by the event.
    Example: "345678901234"

  - `data.eventTimestamp` (string)
    Date and time of the event. Defaults to ISO-8601 format. See dates and
times for more information.
    Example: "2025-05-24T14:15:22Z"

  - `data.userId` (number)
    User assumed as the one who initiated the event. Usually the userId
property and the requestUserId property (below) have the same value.
However, if the request is an API call with Assume-User header then the
userId property identifies the user whose email matches the value in the
Assume-User header.
    Example: 123457654321

  - `data.requestUserId` (number)
    User whose authentication credential is embedded in the request that
initiated the event. For example, if the request is an API call with an
access token then requestUserId identifies the user whose data can be
accessed via the access token (i.e., the user who authorized the creation
of the access token). On the other hand, if the request comes from a UI
session, then requestUserId identifies the user logged-in to the UI.
    Example: 133445566778

  - `data.accessTokenName` (string)
    Name of the access token embedded in the request. This property is omitted
if there's no access token in the request (i.e., it isn't an API call) or
if the access token wasn't given a name when created (only access tokens
generated via the Smartsheet desktop UI can be given a name at creation
time).
    Example: "Test token"

  - `data.source` (string)
    Identifies the client or user agent used to initiate the action.
    Enum: "WEB_APP", "MOBILE_IOS", "MOBILE_ANDROID", "API_UNDEFINED_APP", "API_INTEGRATED_APP", "API_ODBC_DRIVER"

  - `data.additionalDetails` (object)
    Container object for additional event-specific properties. Properties depend upon the event type, but all events include an emailAddress property, representing the user responsible for the event. 

See [Event types](/api/smartsheet/event-types) for event details, including event-specific additionalDetails properties and example event response objects.

  - `data.additionalDetails.emailAddress` (string, required)
    Email address of the user responsible for the event.
    Example: "jane.doe@smartsheet.com"

  - `unavailableSheetIds` (array)
    List of sheet Ids specified in the request that the user does not have access to.

  - `unavailableWorkspaceIds` (array)
    List of workspace Ids specified in the request that the user does not have access to.

## 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.

## Response default 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.