Hi HubSpot team,
I’ve been integrating with the Events API v3 (/events/v3/events/) and ran into several issues that either aren’t documented or are documented incorrectly. Sharing them here for visibility.
1. Pagination is broken
Pagination doesn’t work correctly. The API returns a valid paging.next.after token, but subsequent pages return almost nothing.
Without eventType filter:
– Page 1: 100 results, valid after token
– Page 2: 1 result, no more paging
– Total via pagination: 101
With eventType filter:
– Page 1: 100 results, valid after token
– Page 2: 0 results, no more paging
– Total via pagination: 100
However, setting limit=2147483647 (max signed 32-bit int) returns 160+ results in a single response. The data exists, pagination just doesn’t traverse it.
2. limit parameter doesn’t work as documented
The docs say:
limit (integer) – The maximum number of results to display per page.
This implies pagination, but setting a large limit value returns everything in one request. The parameter controls total results, not page size.
This is actually the only working approach given bug #1, but the documentation is misleading.
3. sort parameter format is wrong in docs
Documentation states:
sort (string[]) – Sort direction based on the timestamp of the event instance, ASCENDING or DESCENDING.
Actual behavior: passing sort=ASCENDING or sort=DESCENDING returns:
{“status”:”error”,”message”:”Only a single sort field ‘occurredAt’ is supported”}The correct format is sort=occurredAt (ascending) or sort=-occurredAt (descending). Standard REST convention with minus prefix for descending, but not what’s documented.
4. id parameter has undocumented requirements
Documentation states you can filter by event instance ID:
id (string[]) – ID of an event instance. IDs are 1:1 with event instances.
When I try this:
{“status”: “error”,
“message”: “Queries using idempotency IDs require the event type 4-96000 be opted into the idempotency index. Idempotency index docs: https://product.hubteam.com/docs/hubspot-framework/unified-events/events/indexes/idempotency.html”
}
The linked URL is internal (product.hubteam.com), not accessible to developers. There’s no public documentation on the “idempotency index” or how to opt event types into it. Standard events like e_visited_page don’t support this filter at all.
Environment:
– API: Events v3 (/events/v3/events/)
– Account: Enterprise tier
– Auth: Private app with static token
Would appreciate clarification on these behaviors and updates to the documentation. Happy to provide more details or test fixes.
Thanks!