How does paging work?

Total request record count to be deprecated: As of the 6th January 2025 the total record count for the V3 endpoints will not be available in the meta object anymore. More information below!

There is 3 different headers associated with paging for the Teamwork API. If you go to the developer tools in your browser, and do a ‘GET’ call. You will see in the headers section if you inspect the browser. There is 3 header values:

  • x-page - the current page being returned

  • x-pages - the total number of pages available

  • x-records - the total number of items available

You can request a specific page by calling the same API call and adding the parameter &page=n where n is the page you want. e.g: &page=2 for page 2, &page=5 for page 5.

You will see throughout the calls paging being used to alter the results.

Code sample for viewing response headers in our Teamwork.com GitHub repo

V3 endpoint meta data

The V3 endpoints include a meta data object in the payload.

The meta object includes the page object and this includes the following keys and values. You can use these values to drive your pagination option.

  • pageOffset: This key value starts at 0 which represents page 1 of your request. As you page up, this number changes. ie: if you add page=3 as a parameter on your request, the pageOffset number will be 2

  • pageSize: This represents the total amount of records returned per page for your request. pageSize is set to 50 by default. Add pageSize=n (where n is the page size you want) as a parameter to change the page size for your request. Max page size for the majority of V3 endpoints is 500.

  • count: This is the total amount of records up to the current page based on the parameters specified. Note that this will not return the total record count for your entire request until hasMore=false. For pagination purposes, the count returned would be (page*pageSize)+1 when hasMore=true.

    Scenario below for a total record count of 267 time entries
    - i.e. given page=2&pageSize=50, we'd return 101 if more pages exist and hasMore is true.
    - i.e: given page=6&pageSize=50, and hasMore=false we will return 267

    Important note: We recently made an alteration to the V3 endpoints for performance reasons where the skipCounts parameter is set to true by default. This parameter can be set to false to return the full record count. This option is available until the 6th January 2025 when we will fully remove the parameter.

  • hasMore: While true, this will let you know there are more pages left in your request. In this case you can change page number from 0 to 1, to 2, etc: ie: page=2. Once this changes to false, this will represent the last page on your request.

V3 endpoint payload page object

GET
page=2&pageSize=50
"meta": {
        "page": {
            "pageOffset": 1,
            "pageSize": 50,
            "count": 101,
            "hasMore": true
        }
    }

V3 endpoint payload page object

GET
page=6&pageSize=50
"meta": {
        "page": {
            "pageOffset": 5,
            "pageSize": 50,
            "count": 267,
            "hasMore": false
        }
    }

Maximum records for a request

We have a limit in place that restricts each request to 50 thousand records. What we mean by a request is a call to an endpoint which includes x amount of pages to reach the total count.

For 50K records the following parameters would be one example of the the maximum you could use pageSize=500&page=100. If you lower the pageSize , the page number can go higher up to the maximum of pageSize * page.

If the data entity you are requesting has more than 50K records, there is a parameter (which may differ between endpoints) that will allow you to request the next 50K records.

Here are some examples of endpoints along with the keys and values required:

V3 get all tasks: Take note of the updatedAt value of the last record in your initial request. When making your next request you can use the updatedAfter parameter with the value noted above.

V3 get all time entries: Take note of the updatedAt value of the last record in your initial request. When making your next request you can use the updatedAfter parameter with the value noted above.

In both cases above, the following format is required yyyy-mm-ddThh:mm:ssZ
ie: page=1&updatedAfter=2024-06-11T09:32:32Z

V1 get all tasks: Take note of the last-changed-on value for the last record in your initial request. When making your next request you can use the updatedAfterDate parameter with the value noted above.

ie: page=1&updatedAfterDate=2024-01-10T12:07:04Z

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.