The documentation on “Associations / Batch / Retrieve asociations” states that you can pass an “after” property which you might receive on a reponse from calling the endpoint. See Retrieve associations - HubSpot docs
Though, I cannot find when the paging kicks in. I tried retrieving associations from a company to contacts for a client of ours, and it gave me all of the 600+ contacts. I know the regular retrieval endpoint for associations in v3 had a 500 record limit, but I cannot find anything about a limit for the batch version on v2026-03.
Also, the “paging” property in the response looks weirdly positioned. It’s in the object inside the “results” property, which holds an array of objects. So theoretically, there could be more “paging” properties in the results. (They might point to paging for the “to” array, but I don’t know).
So, does anybody know when to expect a paged result? Or does the endpoint always give ALL of the associations?
Hey @FvdM,
Thanks for posting in the Community!
I plugged your inquiries into our Docs Assistant in the developer doc you linked. Here’s the context it provided:
"The paging is indeed per-result-object (per from ID), and the after cursor in the input request is paired with the id. The docs do not specify a numeric page-size limit for v2026-03.
The docs don’t state a numeric page size for the v4/v2026-03 batch read endpoint, and the paging is indeed scoped per-result (per from ID).
Based on the docs:
When paging kicks in: The documentation doesn’t publish a specific page-size threshold for the batch read endpoint on v2026-03. It only states “the paging field will only be present if there are more pages and absent otherwise.” The well-known 500/1,000 limits mentioned in the v3 docs apply to single-object reads / batch input sizes, not explicitly to per-from-object output on this endpoint. I wasn’t able to confirm an exact page-size value in the documentation — so in practice, you should treat the presence of paging.next.after as the only reliable signal.
Position of paging: Your reading is correct. Per the OpenAPI schema (PublicAssociationMultiWithLabel), paging lives inside each item of results, alongside that item’s from and to. So each from object can independently have its own paging cursor for its to array — and yes, multiple results in the same response can each carry their own paging. To fetch the next page for a given from, you resend that id in inputs together with the after cursor from its result.
All associations: No guarantee - always loop while any result has a paging.next.after, rather than assuming a single call returns everything.
If you’d like this behavior clarified in the docs (a documented page size would obviously help), you can file it via the Developer Feedback form.
Thanks for your reply! I already put my question in the HubSpot docs API and it gave me the same response. That’s why I turned to the communitiy forums
@FvdM - I looked at the documentation referenced and compared it to the non-batch GET association API. They both seem inconsistent to me in the following ways:
- To understand the potential size of a returned array, you should by convention be able to pass a ?limit=xx query parameter in the call, with limit defualting to 100/500 or whatever. Limit isn’t mention in either page of documentation.
- Per my experience, the ‘after’ value is only present in API return data if there is more data to fetch than was returned in the current call. So, assuming there is an undocumented ‘limit’ option, the ‘after’ value would only be present if the number of records exceeded the ‘limit’ value. So ‘after’ both signals that there is more data available and that the value of after should be used ina follow up call.
I agree that the documented structure of the JSON returned from the batch call is odd in the positioning of the ‘after’ value. I have not experimented with this (I don’t have test data that would stretch such a call) but I am wondering if there are some glitches in the write up as there have been in other doc pages in this transition.
and ofcourse the company record ID in the body of the request, but it still gave me about 690 findings of the “toObjectId” property in the response. That why I suspect the endpoint will return all of the associations, but I’m not sure. We might hit a 1.000 limit in the future, who knows.
If I set the ?limit= to ‘2’, then still, all of the associations are returned. Also the assocation types for assocations to one specific ‘toObjectId’ aren’t limited to 2.
