Stop Conditions Reference

Stop conditions determine when pagination should stop. Incorrect configuration leads to missing data or infinite loops.

Stop Condition Types

Type	Use When
cursor_empty	Cursor becomes null/empty on last page
boolean_flag	API returns has_more: false
comparison	Compare values (e.g., items < limit)

cursor_empty

Stops when the cursor value is null, empty string, or missing from response.

{
  stopCondition: {
    type: "cursor_empty"
  }
}

When to Use

• Cursor becomes null on last page
• Cursor field is omitted on last page
• Cursor becomes empty string ""

Example Responses

Continue (cursor present):

{
  "data": [...],
  "next_cursor": "abc123"
}

Stop (cursor null):

{
  "data": [...],
  "next_cursor": null
}

Stop (cursor missing):

{
  "data": [...]
}

Stop (cursor empty):

{
  "data": [...],
  "next_cursor": ""
}

boolean_flag

Stops when a boolean field equals a specific value.

{
  stopCondition: {
    type: "boolean_flag",
    flagPath: "has_more",
    flagValue: false
  }
}

Configuration

Field	Description	Example
flagPath	JSON path to boolean field	"has_more", "meta.more"
flagValue	Value that indicates stop	false (most common)

When to Use

• API returns has_more: true/false
• API returns is_last_page: true
• Any boolean indicates pagination state

Example: Stripe-style

Continue:

{
  "data": [...],
  "has_more": true
}

Stop:

{
  "data": [...],
  "has_more": false
}

Configuration:

{
  stopCondition: {
    type: "boolean_flag",
    flagPath: "has_more",
    flagValue: false
  }
}

Example: is_last_page

Stop when true:

{
  stopCondition: {
    type: "boolean_flag",
    flagPath: "is_last_page",
    flagValue: true
  }
}

comparison

Stops when a comparison evaluates to true.

{
  stopCondition: {
    type: "comparison",
    comparePath: "data.length",
    compareOperator: "lt",
    compareValue: "{limit}"
  }
}

Configuration

Field	Description	Example
comparePath	JSON path to a number, a ...length array path, or the __page__ token	"data.length", "__page__"
compareOperator	Comparison operator	"lt", "eq", "gte"
compareValue	Number, "{limit}", or "__totalPages__"	100, "{limit}"

Operators

Operator	Meaning	Stops When
lt	Less than	value < compareValue
lte	Less than or equal	value <= compareValue
eq	Equal	value == compareValue
neq	Not equal	value != compareValue
gte	Greater than or equal	value >= compareValue
gt	Greater than	value > compareValue

Special Tokens

These tokens are the only dynamic substitutions the engine performs:

Left side (comparePath):

Token / suffix	Resolves To
__page__	Current page number (1-based)
<path>.length	Length of the array at <path>

Right side (compareValue):

Token	Resolves To
{limit}	Configured defaultLimit (page size)
__totalPages__	Number at the configured response.totalPagesPath

There is no {page}, {offset}, {total}, or {total_pages} placeholder — only the four entries above are recognized.

Common Patterns

Items Less Than Limit

Stop when fewer items returned than requested:

{
  comparePath: "data.length",
  compareOperator: "lt",
  compareValue: "{limit}"
}

Logic: If we asked for 100 items and got 50, we're on the last page.

Empty Results

Stop when no items returned:

{
  comparePath: "data.length",
  compareOperator: "eq",
  compareValue: 0
}

Page Equals Total

Stop when current page reaches total pages. Requires response.totalPagesPath to be set so __totalPages__ can resolve:

{
  comparePath: "__page__",
  compareOperator: "gte",
  compareValue: "__totalPages__"
}

Choosing the Right Stop Condition

Decision Guide

1. Does API return cursor?

   • Cursor becomes null/empty on last page → cursor_empty
   • Cursor always present → Check for has_more

2. Does API return has_more boolean?

   • Yes → boolean_flag
   • No → Use comparison

3. Does API return total count?

   • Yes → Can use comparison with total
   • No → Use items < limit comparison

Recommendation by Pagination Type

Pagination Type	Recommended Stop Condition
Cursor-based	cursor_empty or boolean_flag
Offset-based	comparison (items < limit)
Page-based	comparison (items < limit)

Troubleshooting

Pagination Stops Too Early

Symptoms: Missing data

Check:

1. Stop condition triggering prematurely
2. Path to comparison field correct
3. Operator is correct direction

Common Fixes:

• Change lt to lte
• Fix JSON path to correct field
• Check for off-by-one errors

Pagination Never Stops

Symptoms: Infinite requests

Check:

1. Stop condition configured
2. Condition can actually become true
3. Response matches expected format

Common Fixes:

• Add missing stop condition
• Fix path to cursor/flag field
• Verify API behavior matches expectation

Inconsistent Results

Symptoms: Sometimes works, sometimes loops

Check:

1. API response format varies
2. Edge cases (empty results, single page)
3. Error responses triggering wrong behavior

Common Fixes:

• Add fallback stop conditions
• Handle empty responses explicitly
• Check error handling