Cursor-based pagination
Cursor-based pagination
This guide shows the recommended Hyperfoil pattern for cursor-based pagination using two sequences: one for session initialisation as the first request, and a second that loops over the remaining pages.
Why two sequences?
The scenario uses two separate sequences with different responsibilities:
walkPagesruns the session setup, selects the CSV row, and sends the first request without a cursor. It runs once for each virtual user.pageLoopsends requests usingafterCursorand repeats them until the API returns the final page.
restartSequence restarts the current sequence from its first step. Because the
first step in pageLoop is already the cursor-based request, restarting it fetches the
next page. The setup and first request remain in walkPages, so they are not repeated.
Complete YAML
name: cursor-pagination
http:
host: http://localhost:8080 # replace with your service
phases:
- listPages:
always:
users: 20
duration: 90s
scenario:
initialSequences:
# ── session init: runs once per virtual user ──────────────────────
- walkPages:
- randomCsvRow:
file: conversation-ids.csv
columns:
0: conversationId
1: ownerID
# first page — no cursor
- httpRequest:
GET: /v1/conversations?mode=all&limit=20
headers:
X-API-Key: ${apiKey}
X-User-ID: ${ownerID}
metric: list-conversations-page
handler:
body:
json:
query: .afterCursor
toVar: afterCursor
onCompletion:
conditional:
stringCondition:
fromVar: afterCursor
isSet: true
length:
greaterThan: 0
actions:
- newSequence: pageLoop
sequences:
# ── loop: runs repeatedly until the last page ─────────────────────
- pageLoop:
- httpRequest:
GET: /v1/conversations?mode=all&limit=20&afterCursor=${urlencode:afterCursor}
headers:
X-API-Key: ${apiKey}
X-User-ID: ${ownerID}
metric: list-conversations-page
handler:
body:
json:
query: .afterCursor
toVar: afterCursor
# stop when the response no longer contains afterCursor
- breakSequence:
stringCondition:
fromVar: afterCursor
isSet: false
# cursor is present — fetch the next page
- restartSequence
How the loop terminates
Each iteration of pageLoop follows the same three-step flow:
- The request uses the current value of
afterCursorto fetch a page. - The response handler extracts the next
afterCursorvalue. - Hyperfoil checks whether the variable is set:
- If the API returned another cursor,
breakSequencedoes not stop the sequence andrestartSequencestarts the next iteration ofpageLoop. - If the API omitted
afterCursor,breakSequenceendspageLoopand no further request is made.
- If the API returned another cursor,
response contains afterCursor
-> afterCursor is set
-> breakSequence does not stop pageLoop
-> restartSequence requests the next page
response omits afterCursor
-> afterCursor is unset
-> breakSequence stops pageLoop
-> no restart and no next request
The httpRequest is synchronous by default, so the breakSequence check runs only after
the response body has been processed. This ensures that the decision is based on the
cursor returned by the current page.
Metrics
Both requests share the metric name list-conversations-page, so Hyperfoil
aggregates all page requests into a single histogram.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.