How to use cursor and remaining fields

API
1

Hey there!
I’m trying to figure out how cursor and remaining fields should be used exactly
Take any API, e.g. mints and it says:

cursor: Generated cursor returned by previous query
remaining: Remaining results flag. 1: there are remaining results matching this query, 0: no remaining results

So I’d expect it to work in a way that if remaining: 0 then cursor is empty as there is nothing else left.
But take a look at this two API calls:
First ever mint for the given asset has remaining: 0 and cursor value
If I now use that cursor in another call it will return

{"result":[],"cursor":"","remaining":0}

which is an empty result
So, I’d expect the first query to return an empty cursor as well

Three questions here:

  1. Is the current API behaviour correct?
  2. How exactly those two fields should be used?
  3. Let’s say I want to fetch all the mints ever happened for the given token_address. Is it safe to assume I can only use cursor to go backwards till the very beginning and disregard remaining completely?
2

Answering my own question here
I ended up querying the API till cursor field is not empty, that way I could get all the mints for the given token_address

3

You should use remaining to determine if there are still results to query. Even if remaining: 0, a cursor value is returned. This is expected behavior and you can ignore that value. The cursor is just a base64 encoded string with some filters used to poll the next page of results (if there are any).

4

Hey @Jeffy
It seems then that something is not working quite right
This query returns remaining: 1 and if I go to the returned cursor query it returns no results (empty result array).
I would expect the first query to return remaining: 0 in this case, otherwise this field is kinda useless. If I’m reading a paginated API I don’t want to make an extra call if it returns no results. And I would expect that on your end you also don’t want to get unnecessary calls.

5

That seems odd indeed. I’ve raised an issue for this internally and we’ll look into this. Thanks for flagging!

6

Hey @Enigo I’ve heard back on this.

If the last item returned by the current page is the final item in the entire set, the API will return remaining: 1. This is the current behaviour across all endpoints.

7

Hey @Jeffy
Hm, then I’m still confused how remaining field is designed to be used :thinking:
Let me reiterate, since I’m reading a paginated API I don’t want to make an extra call if it returns no results. So, how would I then know that the current page is the last page?

8

@Enigo I hear you. At the moment, there’s no way to escape that one extra call if the final item on the page is also the last item of the entire set. But you should still be able to use remaining as intended and handle a potential empty response within your code.

Regardless, I’ve raised an improvement request for this as there’s definitely room to make this less confusing.

9

I’m not sure then what the intended use of remaining field is. Since I have a response already I can directly check that result array has some values, no need for an extra field

10

Hey @Jeffy!
Take a look at the following trades API call - it actually returns remaining: 0. So it seems that the current behaviour across endpoints is not really consistent

11

Yeah remaining: 1 + empty next page only happens when the last item on the current page also happens to be the last item in the entire set. A bit of an edge case, really. I’ve raised an improvement request for this as promised.