canonical: https://jentic.com/apis/hubspot.com/hubspot-events-events

# HubSpot Events Events

The HubSpot Events API exposes behavioural event streams captured against contacts in a HubSpot account, returning the chronological list of events with type, occurrence time, and contact context. It supports filtering by event type, object id, and time window so analytics agents can reconstruct customer journeys without scraping the CRM UI. The companion event-types endpoint enumerates which event names are available in the portal, including standard events (page views, form submissions, email opens) and custom behavioural events defined by the account.

## For AI agents

Read behavioural events fired against HubSpot contacts and discover which event types exist in the portal so an agent can reconstruct customer activity timelines.

## Scope

Does not create, update, or delete events, define event schemas, or query CRM object properties - use for reading behavioural event streams and event-type metadata only.

## Capabilities

- Pull a contact's behavioural event timeline filtered by event type and date range
- Enumerate the event types available in a HubSpot portal, including custom behavioural events
- Page through high-volume event streams using the after cursor to feed analytics pipelines
- Correlate marketing email opens, page views, and form submissions against a single contact id
- Backfill product-analytics warehouses with HubSpot event history without touching the CRM UI

## Use cases

### Customer Journey Reconstruction

Pull the full chronological event stream for a HubSpot contact to reconstruct the journey from first page view through form submission, email engagement, and custom in-product events. The Events API returns each event with its occurrence timestamp, event type, and properties, so analytics tools and agents can build per-contact session timelines without polling the CRM record. Useful for support triage, churn analysis, and lead-qualification workflows.

Example prompt: Call GET /events/v3/events/ with objectId=12345 and occurredAfter=2026-05-01 then group the returned events by eventType and emit a timeline.

### Event Type Discovery for Reporting

Before running a report, enumerate the event types defined in a HubSpot account using the event-types endpoint to discover which standard and custom behavioural events are available. The response lists each event name with metadata so an agent can validate that a requested event (for example a custom checkout_completed event) actually exists before querying for occurrences. Avoids 400-style errors from typos and surfaces newly added events automatically.

Example prompt: Call GET /events/v3/events/event-types and return the array of eventType names available in the portal.

### Email Engagement Verification

After a marketing email send, query the Events API to verify which contacts triggered open or click events within a given window. Filtering by eventType and occurredAfter lets an agent confirm engagement against a known campaign send time, returning per-contact occurrence records. Useful for closing the loop on outbound campaigns and triggering downstream nurture flows.

Example prompt: Call GET /events/v3/events/ with eventType=e_visited_page or the relevant email event name, objectId=12345, and occurredAfter set to the campaign send timestamp, then assert the array is non-empty.

### AI Agent Activity Lookup via Jentic

An AI agent embedded in a support tool answers "what has this customer been doing this week?" by searching Jentic for HubSpot event lookup operations, loading the input schema, and executing the call with the contact id and time window. Jentic stores the HubSpot OAuth token in your Jentic One instance, so the agent never touches raw credentials, and the search-load-execute flow takes seconds instead of hours of integration work.

Example prompt: Search Jentic for "get hubspot contact events", load the operation schema for GET /events/v3/events/, and execute with objectId=12345 and occurredAfter=now-7d.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /events/v3/events/ | List behavioural events filtered by contact id, event type, and time window |
| GET | /events/v3/events/event-types | List the event types available in the portal |

## Key resources

- **Events** — Behavioural event occurrences fired against HubSpot contacts, returned with type, time, and properties.
- **Event Types** — Catalogue of standard and custom behavioural event names defined in the portal.

## Why Jentic

- **Setup:** Wiring HubSpot Events by hand means learning its OAuth2 access token auth, targeting the api.hubapi.com host, and paging behavioural event streams yourself. Through Jentic you install once, import HubSpot Events from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Events API reads behavioural event streams and event-type metadata through query parameters rather than resource path ids, so limit the agent to the operations it needs, such as reading events and listing event types. Both operations here are read-only, so no write or delete access is granted unless a different API is added.
- **Credential handling:** Your HubSpot access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get HubSpot contact events' or 'list event types', and Jentic returns the matching Events operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Events Send Event Completions** — Send custom event completions; this API reads them back
- **Events Manage Event Definitions** — Define the schemas for the custom events that this API queries
- **CRM Contacts** — Resolve the contact records that events are fired against
- **Mixpanel** — Dedicated product-analytics event store, broader querying than HubSpot's events feed

## FAQ

### What authentication does the Events Events API use?

The API accepts HubSpot OAuth 2.0 access tokens or private app tokens, sent as a Bearer token in the Authorization header. Through Jentic, the token is stored encrypted in your Jentic One instance and injected at execution time, so the agent never sees the raw secret.

### Can I list all behavioural events for a single contact with this API?

Yes. Call GET /events/v3/events/ with the objectId query parameter set to the contact id and optional occurredAfter, occurredBefore, and eventType filters. The response paginates with a standard after cursor.

### How do I find the custom event names defined in my HubSpot portal?

Call GET /events/v3/events/event-types - the response lists every standard and custom behavioural event name available. Use the returned names as the eventType filter on the events listing endpoint.

### What are the rate limits for the Events Events API?

HubSpot enforces account-level limits of 100 requests per 10 seconds for OAuth and private app tokens on most endpoints, with daily caps that depend on the subscription tier. Check the HubSpot developer portal for the exact tier limits and use the X-HubSpot-RateLimit headers returned with each response.

### How do I fetch a contact's recent events through Jentic?

Run pip install jentic, search for "get hubspot contact events", load the schema for GET /events/v3/events/, and execute with objectId and occurredAfter. Run Jentic One, the self-hosted execution layer, to get an ak_* key.

### Does this API write or modify events?

No. This is a read-only API for querying existing behavioural events and event-type metadata. To send custom event completions use the Events Send Event Completions API, and to define new event schemas use the Events Manage Event Definitions API.

### Can I limit what my agent is allowed to do with the HubSpot Events API?

Yes. Because you run Jentic One yourself and set the rules, you decide which operations the agent may call, so you can allow just GET /events/v3/events/ to read a contact's behavioural event timeline and GET /events/v3/events/event-types to list event names, and nothing else. Both of these operations are read-only, so the agent gets no ability to create, modify, or delete events unless you add a different API. Since the Events API scopes access through query parameters like objectId and eventType rather than resource path ids, your rules govern which endpoints run while the stored HubSpot token is injected only at execution time.