---
title: "List filtered events"
method: POST
path: "/filteredEvents"
tags: ["events"]
---

# List filtered events

`POST /filteredEvents`

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

See [Event types](/api/smartsheet/event-types.md) 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.

## Headers

- `Accept-Encoding` 'deflate' | 'gzip'
- `Authorization` string

## Request body

- FilteredEventsRequest
  - `sheetIds` string[] — Array of sheet Ids used to filter events. Only events related to the specified sheet Ids are returned.
  - `workspaceIds` string[] — Array of workspace Ids used to filter events. Only events related to the specified workspace Ids are returned.
  - `since` string, date-time — 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, date-time — 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.
  - `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`

OK

- object — Stream result properties
  - `nextStreamPosition` string — This string should be passed back to the next GET events call to obtain subsequent events.
  - `moreAvailable` boolean — True if more results are available. This is typically due to event counts exceeding the maxCount parameter passed in.
  - `data` Event[] — List of Events
    - `eventId` string — Unique event identifier.
    - `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.
    - `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.
    - `objectId` integer — The identifier of the object impacted by the event. This property's value depends on the type of the ID in the event object: - If the object ID is a number, this property's value is a numeric ID. - If the object ID is a string, this property's value is `-1`; the `objectIdStr` property's value is the object ID. **DEPRECATED - Use the `objectIdStr` property instead of this property.**
    - `objectIdStr` string — The identifier of the object impacted by the event. For objects with numeric IDs, this field contains the string representation of the numeric ID. For objects with string IDs, this field contains the string ID.
    - `eventTimestamp` string, date-time — Date and time of the event. Defaults to ISO-8601 format. See dates and times for more information.
    - `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.
    - `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.
    - `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).
    - `source` 'WEB_APP' | 'MOBILE_IOS' | 'MOBILE_ANDROID' | 'API_UNDEFINED_APP' | 'API_INTEGRATED_APP' | 'API_ODBC_DRIVER' | 'UNKNOWN' — Identifies the client or user agent used to initiate the action.
    - `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 as well as a `sourceIpAddress` property, representing the responsible's user IP address, if the source of the event is "WEB_APP". See [Event types](/api/smartsheet/event-types) for event details, including event-specific `additionalDetails` properties and example event response objects.
      - `emailAddress` string, required — Email address of the user responsible for the event.
      - `sourceIpAddress` string — IP address of the user responsible for the event.
  - `unavailableSheetIds` string[] — List of sheet Ids specified in the request that the user does not have access to.
  - `unavailableWorkspaceIds` string[] — List of workspace Ids specified in the request that the user does not have access to.

## Other responses

- `400` — Bad Request. See Smartsheet Error Code and Message for details.
- `401` — Unauthorized. See Smartsheet Error Code and Message for details.
- `403` — Forbidden. See Smartsheet Error Code and Message for details.
- `404` — Not Found. See Smartsheet Error Code and Message for details.
- `405` — Method Not Allowed. See Smartsheet Error Code and Message for details.
- `406` — Not Acceptable. See Smartsheet Error Code and Message for details.
- `410` — Gone. See Smartsheet Error Code and Message for details.
- `415` — Gone. See Smartsheet Error Code and Message for details.
- `429` — Gone. See Smartsheet Error Code and Message for details.
- `500` — Internal Server Error. See Smartsheet Error Code and Message for details.
- `default` — Generic Error Payload

---

[API](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference.md) · [All operations](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smartsheet/smartsheet-openapi-reference/versions/b4afda95fb51/schema)