How does paging work?

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 for your request based on the parameters specified.

  • 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 of request
"meta": {
        "page": {
            "pageOffset": 1,
            "pageSize": 500,
            "count": 1163,
            "hasMore": true
        }
    }

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.