The majority of Procore Connect API endpoints support pagination as a means of maximizing performance and responsiveness when dealing with large data sets. By implementing pagination in your application, you can minimize response times for requests and generally improve the end-user experience.

The per_page and page Parameters

The Procore Connect API supports pagination through the use of the per_page and page parameters. Use the per_page parameter to specify how many items you want each page to return. Use the page parameter to specify how link headers are created. Below is an example of using these parameters in a typical API call.

curl -i -H "Authorization: Bearer <your_authorization_code>"

Inspecting the headers shows some helpful information you could use in your application:

HTTP/1.1 200 OK
Cache-Control: no-store, must-revalidate, private, max-age=0
Connection: close
Content-Type: application/json; charset=utf-8
Link: <http://localhost:3000/vapid/punch_items?page=1&per_page=5>; rel="first", <http://localhost:3000/vapid/punch_items?page=2&per_page=5>; rel="prev", <http://localhost:3000/vapid/punch_items?page=30&per_page=5>; rel="last", <http://localhost:3000/vapid/punch_items?page=4&per_page=5>; rel="next",
Per-Page: 5
Server: thin 1.5.1 codename Straight Razor
Set-Cookie: __profilin=p%3Dt; path=/
Set-Cookie: __profilin=p%3Dt; path=/
Set-Cookie: __profilin=p%3Dt; path=/
Total: 150
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-MiniProfiler-Ids: ["9d6t1gn1wr0jemmyn7d7","qdduv0ryqh2gtvrciuey","p9tuluby0fe8zmoez1vs","o62b31dbk6yv35vhk72t","4qteypclwjxlynp6kn3g","8qc93elmb9bfrklzywgb","21efri84vp8ttmppu50d","jzumjv8bei8tvcxse18j","k3k0m745colb4yv2auv1","qgdqq4gx52xjqnoz3mjr"]
X-Request-Id: aa5324bf-1b9a-4a8b-8ac7-7229d5d8d325
X-Runtime: 0.568945
X-XSS-Protection: 1; mode=block

Examining the output above we see:

  • Total: 150 - indicates total number of items to be retrieved.
  • Per-Page: 5 - indicates the number of items per page that will be retrieved.
  • Link: <http://localhost:3000/vapid/punch_items?page=1 per_page=5>;rel="first", <http://localhost:3000/vapid/punch_items?page=2 per_page=5>;rel="prev", <http://localhost:3000/vapid/punch_items?page=30 per_page=5>;rel="last", <http://localhost:3000/vapid/punch_items?page=4 per_page=5>;rel="next"
    - Link headers for the first, prev, last, and next link.

Notes on page parameter:

If page is set to 1, then the header will only include the next and last link.

If page is set to 2, then the header will only include the first, next, and last link.

If page is set to 3 (as in the example), then the header will include the first, prev, next, and last link.

Endpoints that currently do not support pagination

There are a number of Procore Connect API endpoints that currently do not support pagination: