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!
and thank you for sharing your valuable feedback!
