Events API | Events - HubSpot docs

Supported products

Scope requirements

Use the events API to retrieve event types and event occurrences linked to your CRM records. Events include standard events, such as website page views and sequence email opens, as well as custom events and app events. For example, use this API to view a timeline of a contact’s interactions with your content. You can then use this timeline to build a dataset for custom analytics or present a contact timeline in an external application.

Please note: the events API doesn’t include marketing email events, such as opens, clicks, and bounces. To analyze marketing email events, use the email event analytics API.

Retrieve event types

To request all types of events, make a GET request to /events/v3/events/event-types. The response will include all event types, including custom events and app events. The returned list is exhaustive and includes event types regardless of whether an account uses the associated features. This means an event type will be returned even if the account doesn’t or can’t receive occurrences for it. For example, an event type only available to Enterprise subscriptions is returned for an account with a Professional subscription.

Retrieve event occurrences

To retrieve event occurrences, make a GET request to /events/v3/events. Use the following query parameters to retrieve specific occurrences. You can use multiple query parameters to retrieve occurrences that meet specific criteria.

Parameter	Description
`eventType`	Retrieve occurrences for a specific type of event, using the event type’s fully qualified name. The fully qualified name is returned when retrieving event types.
`objectType`	Retrieve occurrences linked to records of a specific object, using the `objectTypeId`.
`objectId`	Retrieve occurrences linked to a specific object record. Specify the type of object with the `objectType` parameter and use the record ID as the `objectId` (e.g., `0-1` for events linked to contact records). Refer to this list of `objectTypeId` values.
`{eventProperty}`	Retrieve occurrences filtered by event occurrence property values. Include the internal name of the property and the value by which to filter.
`properties`	Return only the specified properties in each occurrence’s `properties` object. Pass the parameter multiple times to include multiple properties (e.g., `properties=hs_url&properties=hs_city`). If omitted, all properties are returned.
`occurredAfter` or `occurredBefore`	Retrieve occurrences filtered by when they occurred, after or before a given date and time, inputted as an ISO 8601 string or UNIX-formatted timestamp.
`id`	Retrieve an individual occurrence by its unique ID. Each event occurrence’s `id` value is returned when retrieving events.

Below are some examples of requests you can build using the above query parameters:

Goal	Request URL
Retrieve all event occurrences of the event type `e_visited_page`	`/events/v3/events/?eventType=e_visited_page`
Retrieve all event occurrences linked to contacts	`/events/v3/events/?objectType=contact`
Retrieve event occurrences linked to a specific contact record	`/events/v3/events/?objectType=contact&objectId=224834`
Retrieve event occurrences of `e_visited_page` linked to a specific contact record	`/events/v3/events/?objectType=contact&objectId=224834`
Retrieve occurrences of `e_visited_page` from Chrome linked to a specific contact	`/events/v3/events/?eventType=e_visited_page&objectType=contact&objectId=224834`
Retrieve occurrences of `e_visited_page` after January 5, 2026 at 11:00 am EST	`/events/v3/events/?eventType=e_visited_page&occurredAfter=2026-01-05T11:00:00-05:00`
Retrieve an individual event occurrence	`/events/v3/events/?id=1234`
Retrieve `e_visited_page` occurrences with only the URL and city properties	`/events/v3/events/?eventType=e_visited_page&properties=hs_url&properties=hs_city`

Your response will include details about the specific event occurrences. For example, the response for GET /events/v3/events/?eventType=e_visited_page&occurredAfter=2026-01-05T11:00:00-05:00 would look similar to:

{
  "results": [
    {
      "objectType": "CONTACT",
      "objectId": "191425954166",
      "eventType": "e_visited_page",
      "occurredAt": "2026-01-08T17:01:22.900Z",
      "id": "leviathan-d946c738-6a0a-35f2-9e1a-d620c37eb444-1767891682900",
      "properties": {
        "hs_base_url": "website.com/blog/blog-post",
        "hs_url": "https://website.com/blog/blog-post",
        "hs_is_virtual_url": "false",
        "hs_region": "or",
        "hs_is_virtual_referrer": "false",
        "hs_is_external": "false",
        "hs_page_title": "Blog post name",
        "hs_device_name": "iPhone",
        "hs_content_type": "BLOG_POST",
        "hs_hash_id": "484673",
        "hs_is_new_cookie": "true",
        "hs_language": "en",
        "hs_log_line_timestamp": "1767891682900",
        "hs_browser": "Safari mobile",
        "hs_country": "us",
        "hs_canonical_url": "website.com/blog/blog-post",
        "hs_url_domain": "website.com",
        "hs_language_variant": "91625708804",
        "hs_operating_system": "iOS",
        "hs_url_path": "/blog/blog-post",
        "hs_processed_timestamp": "1767891683895",
        "hs_targeted_content_aggregation": "default",
        "hs_content_group_id": "23815039668",
        "hs_device_type": "Smartphone",
        "hs_qualified_region": "us_or",
        "hs_visit_source": "organic",
        "hs_page_id": "91625708804",
        "hs_referrer": "https://www.google.com/",
        "hs_original_canonical_url": "https://website.com/blog/blog-post",
        "hs_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1 Mobile/15E148 Safari/604.1",
        "hs_is_amp": "true",
        "hs_city": "madras",
        "hs_browser_version_major": "18",
        "hs_title": "Blog post name",
        "hs_is_in_chat_view": "false",
        "hs_is_contact": "false",
        "hs_utm_campaign": "",
        "hs_visit_source_details_2": "GOOGLE",
        "hs_original_content_type": "BLOG_POST",
        "hs_vendor": "Apple",
        "hs_content_id": "91625708804",
        "hs_visit_source_details_1": "Unknown keywords (SSL)",
        "hs_browser_type": "Mobile browser"
      }
    },
    {
      "objectType": "CONTACT",
      "objectId": "192718366767",
      "eventType": "e_visited_page",
      "occurredAt": "2026-01-13T17:49:23.736Z",
      "id": "leviathan-86c572da-b3a3-327b-a06d-c85b9dae68db-1768326563736",
      "properties": {
        "hs_base_url": "website.com/blog/blog-post-two",
        "hs_url": "https://website.com/blog/blog-post-two",
        "hs_is_virtual_url": "false",
        "hs_region": "on",
        "hs_is_virtual_referrer": "false",
        "hs_is_external": "false",
        "hs_page_title": "Blog post two",
        "hs_content_type": "BLOG_POST",
        "hs_hash_id": "108272",
        "hs_is_new_cookie": "true",
        "hs_language": "en",
        "hs_log_line_timestamp": "1768326563736",
        "hs_browser": "Chrome Mobile",
        "hs_country": "ca",
        "hs_canonical_url": "website.com/blog/blog-post-two",
        "hs_url_domain": "website.com",
        "hs_language_variant": "89588592281",
        "hs_operating_system": "Android",
        "hs_url_path": "/blog/blog-post-two",
        "hs_processed_timestamp": "1768327491453",
        "hs_targeted_content_aggregation": "default",
        "hs_content_group_id": "23815039668",
        "hs_device_type": "Smartphone",
        "hs_qualified_region": "ca_on",
        "hs_visit_source": "organic",
        "hs_page_id": "89588592281",
        "hs_referrer": "android-app://com.google.android.googlequicksearchbox/",
        "hs_original_canonical_url": "https://website.com/blog/blog-post-two",
        "hs_user_agent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Mobile Safari/537.36",
        "hs_is_amp": "true",
        "hs_city": "milton",
        "hs_browser_version_major": "143",
        "hs_title": "Blog post two",
        "hs_is_in_chat_view": "false",
        "hs_is_contact": "false",
        "hs_leviathan_linked_vids": "192718366767",
        "hs_utm_campaign": "",
        "hs_visit_source_details_2": "GOOGLE",
        "hs_original_content_type": "BLOG_POST",
        "hs_content_id": "89588592281",
        "hs_visit_source_details_1": "Unknown keywords (SSL)",
        "hs_browser_type": "Mobile browser"
      }
    }
  ]
}

​Retrieve event types

​Retrieve event occurrences

Retrieve event types

Retrieve event occurrences