---
updatedAt: 2026-04-20T19:14:52.000Z
agentTools:
  projectIndex: https://developers.nutshell.com/llms.txt
---

# Get a list of events

Retrieve a feed of events. Events, also known as change logs, are a record of everything that happened in Nutshell. They're used to power notifications and timelines among other things.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Nutshell API",
    "description": "The most powerful API in the world",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "app.nutshell.com/rest"
    }
  ],
  "paths": {
    "/events": {
      "get": {
        "tags": [
          "Events (Timeline)"
        ],
        "summary": "Get a list of events",
        "description": "Retrieve a feed of events. Events, also known as change logs, are a record of everything that happened in Nutshell. They're used to power notifications and timelines among other things.",
        "operationId": "975fac2bed2a6a346717a88cfcdb9324",
        "parameters": [
          {
            "name": "max_id",
            "in": "query",
            "description": "Retrieve a feed of events with an ID less than or equal to than the specified ID",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since_id",
            "in": "query",
            "description": "Retrieve a feed of events with an ID greater than the specified ID",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_time",
            "in": "query",
            "description": "Retrieve a feed of events that occurred before the specified time",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "since_time",
            "in": "query",
            "description": "Retrieve a feed of events that occurred after the specified time",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "entity_id",
            "in": "query",
            "description": "Retrieve a feed of events related to a specific entity",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The number of events to return",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "events",
            "in": "query",
            "description": "Opt in to additional event types: comments, mailchimp, followup, constantContact, emailInteraction, assignments, formSubmissions",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "comments",
                  "mailchimp",
                  "followup",
                  "constantContact",
                  "emailInteraction",
                  "assignments",
                  "formSubmissions"
                ]
              }
            }
          },
          {
            "name": "filters[payload][]",
            "in": "query",
            "description": "Retrieve a feed of events related to a type of entity",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "accounts",
                  "activities",
                  "assignments",
                  "chats",
                  "companyEnrichment",
                  "constantContact",
                  "contacts",
                  "emails",
                  "emailInteraction",
                  "formSubmissions",
                  "inbox_threads",
                  "leadUpdates",
                  "leads",
                  "marketingEmails",
                  "mcfxSessions",
                  "notes",
                  "queued",
                  "ticketMessages",
                  "undelivered",
                  "unshared"
                ]
              }
            }
          },
          {
            "name": "filters[creator][]",
            "in": "query",
            "description": "Retrieve a feed of events caused by a specific user or team",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "filters[emailEntityType][]",
            "in": "query",
            "description": "Whether to receive email sent or received events. Requires a creator filter",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "sender",
                  "recipient"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "commentLinkIds": {
        "description": "Returns an array of all potential link configurations for the current object.\nSupported keys for each link config are:\n- string type\nThe `type` key of the top-level link configuration.\n- array groups\nWhich groups this link will be included in; 'base' for all.\n- array compoundGroups\nWhich groups will include the linked model(s) as compound documents by default.\n- string urlPrefix\nOverwrites the `href` link config value with i.e. \"https://app01.nutshell.com/rest/$urlPrefix\".\n- boolean isResourceObject\nIf `true`, no top-level link config will be included in the response for this\nlink. Every linked model will be render as a resource object of the form:\n{ id: \"ApiId\", type: \"ApiType\", href: \"ApiHref\" }",
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "EventResponse": {
        "description": "A full response object for an event-related endpoint.",
        "properties": {
          "meta": {
            "allOf": [
              {
                "$ref": "#/components/schemas/meta"
              },
              {
                "properties": {
                  "previous": {
                    "description": "The URL to the previous page of results",
                    "type": "string"
                  }
                },
                "type": "object"
              },
              {
                "properties": {
                  "next": {
                    "description": "The URL to the next page of results",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ChangeLogEntry"
                },
                {
                  "properties": {
                    "links": {
                      "$ref": "#/components/schemas/eventLinkIds"
                    }
                  },
                  "type": "object"
                }
              ]
            }
          }
        },
        "type": "object"
      },
      "ChangeLogEntry": {
        "properties": {
          "id": {
            "description": "The API ID of this entity, formatted {integer}-{entityType}",
            "type": "string",
            "example": "3-contacts"
          },
          "createdTime": {
            "type": "integer"
          },
          "actorType": {
            "description": "The type of entity that performed the action.",
            "type": "string",
            "example": "users"
          },
          "payloadType": {
            "description": "The type of entity that was changed",
            "type": "string",
            "example": "contacts"
          },
          "action": {
            "description": "What type of change took place",
            "type": "string",
            "example": "create"
          },
          "changes": {
            "$ref": "#/components/schemas/changes"
          },
          "count": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "eventLinkIds": {
        "properties": {
          "actor": {
            "type": "string"
          },
          "payloads": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "comments": {
            "$ref": "#/components/schemas/commentLinkIds"
          }
        },
        "type": "object"
      },
      "changeLogChange": {
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "changes": {
        "description": "The changed values associated with the event",
        "type": "array",
        "items": {
          "properties": {
            "attribute": {
              "description": "What value of the entity was changed",
              "type": "string",
              "example": "value"
            },
            "oldValue": {
              "$ref": "#/components/schemas/changeLogChange"
            },
            "newValue": {
              "$ref": "#/components/schemas/changeLogChange"
            }
          },
          "type": "object"
        }
      },
      "meta": {
        "description": "Information about the Nutshell instance making the request",
        "properties": {
          "instanceId": {
            "description": "The Nutshell instance ID",
            "type": "string",
            "example": "12345"
          },
          "siteId": {
            "description": "Site ID for WebFX customers",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "tags": [
    {
      "name": "Events (Timeline)",
      "description": "Events (Timeline)"
    }
  ]
}
```