Hi, in the documentation of the kratos rest api /admin/identities endpoints (https://www.ory.sh/docs/kratos/reference/api#tag/identity) is stated, that page parameter is not sequential. How can a client know, which is the next valid page to query?

Hey 👋 Apparently, it’s conveyed in Link header of the response. At least that’s what I can see in response headers.

curl -q -H 'Authorization: Bearer '$ORY_PAT $ORY_HTTP_BASE'/admin/identities?per_page=1' -v
…
< link: <https://….projects.oryapis.com/identities?page=0&page_size=1&page_token=eyJvZmZzZXQiOiIwIiwidiI6Mn0&per_page=1>; rel="first",<https://….projects.oryapis.com/identities?page=0&page_size=1&page_token=eyJvZmZzZXQiOiIwIiwidiI6Mn0&per_page=1>; rel="prev"

Would’ve been nice to have this documented though.

hi, thanks for the info! i should be able to parse the link header so this is ok for my case

Looks like you’re getting onto the last page with your request. Do you make a request with an explicit

page

query parameter by any chance?

yes, I always added a page param

Probably we’re expected to call the paginated APIs without page to get the first one (at least I hope so), and then follow the links.

I see, I will try that

You’re welcome!

yes, i see that as well. Probably safest is to call /identities with perPage and no page to start, then use “next”, until no “next” is present

The links Ory gives us back have an additional

page_token

parameter, which seemingly makes

page=1

work properly.

same issue here. our code base parses the link header and looks for next and last. but there is a bug where the last page is not returned when the end is hit. Any ideas if there is a bug in the codebase? here is the code (using kratos v0.11.1): https://github.com/GaloyMoney/galoy/blob/422f9e66715e29001dbe39abe5ac503a50513cdf/src/services/kratos/identity.ts#L48-L76

const identities: Identity[] = []
      let totalCount = 0

      let hasNext = true

      let page: number | undefined = 0

      while (hasNext) {
        // Note: this call is paginated, return 250 records `perPage` by default
        const res = await kratosAdmin.listIdentities({ perPage, page })
        identities.push(...res.data)

        totalCount = Number(res.headers["x-total-count"])

        page = getNextPage(res.headers.link)
        hasNext = page !== undefined && totalCount !== 0
      }

      // * fixes bug in kratos res.headers.link not returning last page properly
      const pageCount = totalCount / perPage
      const isPageCountWholeNumber = pageCount % 1 // 0 means its a whole number, therefore, we can skip because no partial last page of data exists
      if (isPageCountWholeNumber !== 0) {
        const lastPageNum = Math.ceil(totalCount / perPage)
        const lastPageRes = await kratosAdmin.listIdentities({
          perPage,
          page: lastPageNum,
        })
        identities.push(...lastPageRes.data)
      }

Hmmm… There is definitely at least one bug there. I have a toy project with 4 identities at the moment, and when I use

page_size=3

I can’t access the 4th identity at all.

looks the same for me, maybe should open an issue?

We do, but I’m a bit flooded with other things at work to file a properly explained issue. Feel free to create one. Or maybe someone from Ory devs/QAs will see this thread and does it for us 🤞

there is an issue already opened here https://github.com/ory/kratos/issues/2834 maybe we can add more details to the issue

I finally had some time to look into it (again). For me it looks like a bug in the generation of the link URLs. If I test with 6 total identities in kratos and request with per_page=4 (without page number). I get rel=“next” with page=1 (which returns the same results as without page number). When I then request page=2 I get the missing 2 identities. Have to test what it does with uneven numbers.