# Retrieve a list of events

GET https://api.close.com/api/v1/event/

The list of available object types and actions is available [here](/resources/event-log/list-of-events/). The event log can be filtered by the following parameters:

- `date_updated`: The date/time of when the event was last updated, in ISO format. Can be filtered by range (`date_updated__gte=X&date_updated__lte=Y`). Note: For pagination, it is recommended to use cursors instead of this filter (see below).
- `object_type`: If specified, only events for objects of a given type are returned. Example: `object_type=lead`
- `object_id`: If specified, only events for the given object are returned. No related object events are returned. Example: `object_id=lead_123`
- `action`: Only events of specified actions are returned. Example: `action=deleted`
- `lead_id`: If specified, events for the given lead, including any of its related objects (contacts, activities, opportunities, tasks) are returned.
- `user_id`: Only return events of the given user.
- `request_id`: Only events emitted while processing this specific API request.

Only certain combinations of filters are supported. `date_updated` can be optionally used with any allowed filter combination. Supported combinations are:

- `object_type` and `object_id`
- `object_type` and `action`
- `object_id` and `action`
- `lead_id` and `object_type`
- `lead_id`, `object_type` and `action`
- `lead_id`, `user_id` and `object_type`
- `lead_id`, `user_id`, `object_type` and `action`
- `lead_id` and `user_id`
- `user_id` and `object_id`
- `user_id`, `object_id` and `action`
- `user_id` and `object_type`
- `user_id`, `object_type` and `action`
- Just `lead_id`
- Just `user_id`
- Just `request_id`

The response is a dictionary with the following fields:

- `data`: A list of events (dictionaries), using the format outlined in “Event format”.
- `cursor_next`: Cursor string to retrieve the next page of events, i.e. events before the given ID (earlier date), or `null` if no more objects are available.
- `cursor_previous`: Cursor string to retrieve the previous page of events, i.e. events after the given ID (later date), or `null` if no more objects are available.

Events are always ordered by date (latest first), i.e. the `date_updated` field. Note that even though `date_created` and `date_updated` may only have millisecond-precision, two or more events for the same object are guaranteed to be returned in the proper order.

The endpoint supports the following parameters for pagination, and does *not* support `_skip`:

- `_cursor`: Pagination using a cursor string (`cursor_next` or `cursor_previous` from a previous response). Note that you still need to supply any other filters (except for `date_updated`) that were used in the previous query.
- `_limit`: Maximum number of events to return (capped at and defaulting to 50).

Cursors are a reliable way to go to the next or previous page of events (unlike filtering by `date_updated`, where you may need to account for and filter out multiple events happening in the same millisecond). However, cursors are not designed to stream new events: Events may be visible through the API in a different order than they were triggered (but the ordering returned by the API is correct). Also, event consolidation of multiple recent events to the same object may occur. To avoid missing recent events when paginating, we recommend to scan the latest five minutes of events.

In the example response, to retrieve the next older batch of events, specify `_cursor=cursor2`.

Reference: https://developer.close.com/api/resources/events/list

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: Close API
  version: 1.0.0
paths:
  /event/:
    get:
      operationId: list
      summary: Retrieve a list of events
      description: >-
        The list of available object types and actions is available
        [here](/resources/event-log/list-of-events/). The event log can be
        filtered by the following parameters:


        - `date_updated`: The date/time of when the event was last updated, in
        ISO format. Can be filtered by range
        (`date_updated__gte=X&date_updated__lte=Y`). Note: For pagination, it is
        recommended to use cursors instead of this filter (see below).

        - `object_type`: If specified, only events for objects of a given type
        are returned. Example: `object_type=lead`

        - `object_id`: If specified, only events for the given object are
        returned. No related object events are returned. Example:
        `object_id=lead_123`

        - `action`: Only events of specified actions are returned. Example:
        `action=deleted`

        - `lead_id`: If specified, events for the given lead, including any of
        its related objects (contacts, activities, opportunities, tasks) are
        returned.

        - `user_id`: Only return events of the given user.

        - `request_id`: Only events emitted while processing this specific API
        request.


        Only certain combinations of filters are supported. `date_updated` can
        be optionally used with any allowed filter combination. Supported
        combinations are:


        - `object_type` and `object_id`

        - `object_type` and `action`

        - `object_id` and `action`

        - `lead_id` and `object_type`

        - `lead_id`, `object_type` and `action`

        - `lead_id`, `user_id` and `object_type`

        - `lead_id`, `user_id`, `object_type` and `action`

        - `lead_id` and `user_id`

        - `user_id` and `object_id`

        - `user_id`, `object_id` and `action`

        - `user_id` and `object_type`

        - `user_id`, `object_type` and `action`

        - Just `lead_id`

        - Just `user_id`

        - Just `request_id`


        The response is a dictionary with the following fields:


        - `data`: A list of events (dictionaries), using the format outlined in
        “Event format”.

        - `cursor_next`: Cursor string to retrieve the next page of events, i.e.
        events before the given ID (earlier date), or `null` if no more objects
        are available.

        - `cursor_previous`: Cursor string to retrieve the previous page of
        events, i.e. events after the given ID (later date), or `null` if no
        more objects are available.


        Events are always ordered by date (latest first), i.e. the
        `date_updated` field. Note that even though `date_created` and
        `date_updated` may only have millisecond-precision, two or more events
        for the same object are guaranteed to be returned in the proper order.


        The endpoint supports the following parameters for pagination, and does
        *not* support `_skip`:


        - `_cursor`: Pagination using a cursor string (`cursor_next` or
        `cursor_previous` from a previous response). Note that you still need to
        supply any other filters (except for `date_updated`) that were used in
        the previous query.

        - `_limit`: Maximum number of events to return (capped at and defaulting
        to 50).


        Cursors are a reliable way to go to the next or previous page of events
        (unlike filtering by `date_updated`, where you may need to account for
        and filter out multiple events happening in the same millisecond).
        However, cursors are not designed to stream new events: Events may be
        visible through the API in a different order than they were triggered
        (but the ordering returned by the API is correct). Also, event
        consolidation of multiple recent events to the same object may occur. To
        avoid missing recent events when paginating, we recommend to scan the
        latest five minutes of events.


        In the example response, to retrieve the next older batch of events,
        specify `_cursor=cursor2`.
      tags:
        - subpackage_events
      parameters:
        - name: _limit
          in: query
          description: Number of results to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: _skip
          in: query
          description: Number of results to skip before returning, for pagination.
          required: false
          schema:
            type: integer
            default: 0
        - name: object_type
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: object_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: lead_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: action
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: user_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__gt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__gte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__lt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__lte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: Authorization
          in: header
          description: Basic authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/events_list_Response_200'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Any type
servers:
  - url: https://api.close.com/api/v1
components:
  schemas:
    events_list_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: events_list_Response_200
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: basic
    OAuth2:
      type: http
      scheme: bearer

```