Pagination

Overview

Some list operations return one page at a time. Others return the complete list in one response. You cannot tell the two apart from the URL, so this page lists every published list operation and says which kind it is.

On a paged operation you choose the page with two query parameters, and the response tells you how many pages there are. The rules are the same in v1 and v2. The difference is that far fewer v2 list operations are paged.

Query parameters

GET https://app{server-number}.timelog.com/{account}/api/v1/project/get-all?$page=2&$pagesize=50

Things to know about these parameters:

• The default page size is small. If you send neither parameter, a paged operation returns only the first 10 items. A client that reads one response and stops will miss data.
• There is no documented maximum page size. The API layer does not enforce one. Larger pages mean larger and slower responses; for example, large pages of the currency list can be slow. Choose a size that suits your client.
• Both values must be numbers. A non-numeric $page or $pagesize fails with 500. See Errors.
• There are no generic sort or filter parameters. Each operation has its own fixed order and its own filter parameters, if it has any. The operation's reference page documents both.
• Only paged operations use them. Sending $page or $pagesize to an operation that is not paged does not page its response.

Paging values in the response

A paged operation returns three list-level values in Properties, next to Entities:

All three are strings, not numbers. Parse them before you compare or calculate with them.

Example: GET /v1/country/get-all with the default page size (three of the ten entities shown).

{
  "Properties": { "TotalRecord": "244", "TotalPage": "25", "PageNumber": "1" },
  "Entities": [
    { "Properties": { "CountryID": 1, "Country": "Afghanistan", "ISO": "AF", "DefaultCurrencyID": 0 } },
    { "Properties": { "CountryID": 2, "Country": "Albanien", "ISO": "AL", "DefaultCurrencyID": 0 } },
    { "Properties": { "CountryID": 53, "Country": "Amerikanske Jomfruøer", "ISO": "VI", "DefaultCurrencyID": 31 } }
  ],
  "Links": [
    { "Href": "https://app{server-number}.timelog.com/{account}/api/v1/country/get-all", "Rel": "self" }
  ]
}

244 countries at 10 per page gives 25 pages.

A list that is not paged has no TotalRecord, TotalPage or PageNumber. It returns every item in Entities. For the general list shape, and for what an empty paged list looks like, see Response envelope.

Walking all pages

Use the following loop for any operation in the paged table:

1. Request $page=1 with the page size you want.
2. Read the items from Entities. If Entities is missing, the page is empty: stop.
3. Parse PageNumber and TotalPage as integers. If PageNumber is greater than or equal to TotalPage, stop.
4. Otherwise, request the next page and go back to step 2.

Keep both stop conditions. On some operations TotalPage is higher than the real number of pages, and the last pages come back empty. The empty-page check stops the loop there. An empty result also returns "TotalPage": "0", so step 3 stops it as well.

A generic sketch in JavaScript:

// Fetches every item of a paged list operation.
// `url` is the operation URL without $page / $pagesize; `headers` carries your Authorization header.
async function fetchAllPages(url, headers, pageSize = 100) {
  const items = [];
  const separator = url.includes("?") ? "&" : "?";

  for (let page = 1; ; page++) {
    const response = await fetch(`${url}${separator}$page=${page}&$pagesize=${pageSize}`, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const body = await response.json();

    // A missing Entities member means an empty page.
    if (!body || !body.Entities) break;
    items.push(...body.Entities.map((entity) => entity.Properties));

    // Paging values are strings.
    const pageNumber = parseInt(body.Properties?.PageNumber ?? "0", 10);
    const totalPage = parseInt(body.Properties?.TotalPage ?? "0", 10);
    if (pageNumber >= totalPage) break;
  }

  return items;
}

The sketch has no retry or rate-limit handling. Add those for production use.

Which list operations are paged

The tables below cover every published list operation. Use them to decide whether you need the paging loop.

Paged operations

These operations accept $page and $pagesize (defaults 1 and 10) and return TotalRecord, TotalPage and PageNumber. Unless a note says otherwise, a page counts items in Entities.

Paged with skip and take

These v2 operations page with their own skip (items to skip) and take (items to return) query parameters instead of $page and $pagesize. They return no total count. Request the next block until a response has no Entities, or fewer than take items.

Unless a note says otherwise, skip and take are required: leaving either one out returns 404. No maximum is documented for take.

Not paged

These operations return the complete list in one response. They do not page it, even if you send $page or $pagesize. Some return a fixed maximum number of items; the notes say where.

Not documented