# Change events

`GET https://api.airtable.com/v0/meta/enterpriseAccounts/{enterpriseAccountId}/changeEvents`

Retrieve change events for enterprise bases. These change events are available for 14 days from the date of the event.

This endpoint requires change events to be enabled for your enterprise account and toggled on in your enterprise admin panel. Please contact your account team or support to start this process. Events are generated only after you turn change events on in your admin panel.

## Requirements

- **Authentication:** [Personal access token](https://airtable.com/developers/web/api/authentication.md#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication.md#types-of-token)
- **Scope:** [`enterprise.changeEvents:read`](https://airtable.com/developers/web/api/scopes.md#enterprise-change-events-read)
- **User role:** Enterprise admin
- **Billing plans:** Enterprise Scale

## Path parameters

- `enterpriseAccountId: string`

## Query parameters

- `startTime: string` — optional

  Earliest change event to retrieve (inclusive), in ISO 8601 date time format. Optional.

- `endTime: string` — optional

  Latest change event to retrieve (exclusive), in ISO 8601 date time format. Optional.

- `pageSize: number` — optional

  The number of records per page. Maximum value of 100; defaults to 10.

- `offset: string` — optional

  If there may be more to retrieve, an **offset** is returned.
  Pass the **offset** to the next call to retrieve the next page. Do not pass **offset** when retrieving the first page.

## Response format

- `offset: string` — optional

  Pagination token. Pass this value as the **offset** query parameter to retrieve the next page.

- `events: array<object>` — required

  Events are returned newest to oldest.

  - `id: string` — required

  - `type: string` — required

    The type of event. **base_modified** is currently the only value.

  - `actor: Change-events-actor` — required

    The actor that caused the change event. Note that this could be a user or an internal system.

  - `eventTimestamp: string` — required

    A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z"

  - `objectId: string` — required

    ID of the affected object.

  - `objectType: "base"` — required

    Type of the affected object. Currently only 'base'.

  - `timestamp: string` — required

    A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z"

  - `context: object` — required

    Additional context about the change event.

    - `baseId: string` — required

      Base ID, a unique identifier for a base.

    - `applicationId: string` — optional

      Deprecated. Use `baseId` instead.

    - `actionId: string` — optional

  - `origin: object` — required

    Contains additional information about the request origin, including IP address.

    - `ipAddress: string` — required

  - `payload: object` — required

    Payload of base changes. This captures changes to base's schema, cell values, attachment URLs, and record comments.

    Each **created\***, **destroyed\***, **changed\*** field is optional.

    Refer to [field types](https://airtable.com/developers/web/api/field-model.md) for more information about cell value payloads.

    - `data: Change-events-data` — required

    - `version: "v0"` — required

### Example — Success response

```sh
curl "https://api.airtable.com/v0/meta/enterpriseAccounts/{enterpriseAccountId}/changeEvents" \
-H "Authorization: Bearer YOUR_TOKEN"
```

```json
{
  "events": [
    {
      "actor": {
        "type": "user",
        "user": {
          "email": "foo@bar.com",
          "id": "usrL2PNC5o3H4lBEi",
          "name": "Jane Doe"
        }
      },
      "context": {
        "baseId": "appLkNDICXNqxSDhG"
      },
      "eventTimestamp": "2022-02-01T21:25:05.663Z",
      "id": "01FYFFDE39BDDBC0HWK51R6GPF",
      "objectId": "appLkNDICXNqxSDhG",
      "objectType": "base",
      "origin": {
        "ipAddress": "1.2.3.4"
      },
      "payload": {
        "data": {
          "changedTablesById": {
            "tbltp8DGLhqbUmjK1": {
              "changedFieldsById": {
                "fldoi0c3GaRQJ3xnI": {
                  "current": {
                    "name": "new name"
                  },
                  "previous": {
                    "name": "previous name"
                  }
                }
              },
              "changedMetadata": {
                "current": {
                  "description": "table description",
                  "name": "table name"
                },
                "previous": {
                  "description": "previous name",
                  "name": "previous name"
                }
              },
              "changedRecordsById": {
                "rec560UJdUtocSouk": {
                  "current": {
                    "cellValuesByFieldId": {
                      "fldgdCnvrkNsrWnDn": [
                        {
                          "id": "rec560UJdUtocSouk",
                          "name": "Record primary column value"
                        }
                      ],
                      "fldoi0c3GaRQJ3xnI": "Updated hello world"
                    }
                  },
                  "previous": {
                    "cellValuesByFieldId": {
                      "fldgdCnvrkNsrWnDn": null,
                      "fldoi0c3GaRQJ3xnI": "Hello world"
                    }
                  }
                }
              },
              "changedRecordsMetadataById": {
                "rec560UJdUtocSouk": {
                  "changedCommentsById": {
                    "comB5z37Mg9zaEPw6": {
                      "current": {
                        "text": "updated comment text"
                      },
                      "previous": {
                        "text": "previous comment text"
                      }
                    }
                  },
                  "createdCommentsById": {
                    "comB5z37Mg9zaEPw6": {
                      "text": "comment text"
                    }
                  },
                  "destroyedCommentIds": [
                    "comB5z37Mg9zaEPw6"
                  ]
                }
              },
              "createdFieldsById": {
                "fldoi0c3GaRQJ3xnI": {
                  "name": "new name",
                  "type": "number"
                }
              },
              "createdRecordsById": {
                "rec560UJdUtocSouk": {
                  "cellValuesByFieldId": {
                    "fldoi0c3GaRQJ3xnI": "Hello world"
                  },
                  "createdTime": "2022-02-01T21:25:05.663Z"
                }
              },
              "destroyedFieldIds": [
                "fldoi0c3GaRQJ3xnI"
              ]
            }
          },
          "createdTablesById": {
            "tbltp8DGLhqbUmjK1": {
              "fieldsById": {
                "fldoi0c3GaRQJ3xnI": {
                  "name": "Name",
                  "type": "singleLineText"
                }
              },
              "metadata": {
                "description": "new table description",
                "name": "new table"
              },
              "recordsById": {
                "rec560UJdUtocSouk": {
                  "cellValuesByFieldId": {
                    "fldoi0c3GaRQJ3xnI": "Hello world"
                  },
                  "createdTime": "2022-02-01T21:25:05.663Z"
                }
              },
              "recordsMetadataById": {
                "rec560UJdUtocSouk": {
                  "commentsById": {
                    "comB5z37Mg9zaEPw6": {
                      "text": "comment text"
                    }
                  }
                }
              }
            }
          },
          "destroyedTableIds": [
            "tbltp8DGLhqbUmjK1"
          ]
        },
        "version": "v0"
      },
      "timestamp": "2022-02-01T21:25:05.663Z",
      "type": "base_modified"
    }
  ],
  "offset": "01FYET2W5BGQ24DXT5C4AG36PR"
}
```

## Error responses

### 422

**Invalid offset** — Invalid **offset**. See error message for exact reason.

```json
{
  "error": {
    "message": "Offset token is invalid for this query",
    "type": "INVALID_OFFSET_VALUE"
  }
}
```

**Invalid pageSize** — Invalid **pageSize**. See error message for exact reason.

```json
{
  "error": {
    "message": "Maximum pageSize is 100",
    "type": "INVALID_PAGE_SIZE_ARGUMENT"
  }
}
```

**Invalid time** — Invalid **startTime** or **endTime**. See error message for exact reason.

```json
{
  "error": {
    "message": "startTime cannot be same or after endTime",
    "type": "INVALID_TIME_RANGE"
  }
}
```