Pagination Planner

integration.pagination_plan

ProductionBounded custom (Class B)Deterministicstrictinstantv1.0.0

No network

Overview

You send mode OFFSET_LIMIT or PAGE_NUMBER, required totalItems and pageSize. OFFSET_LIMIT uses startOffset default 0. PAGE_NUMBER uses base ZERO or ONE (default ONE) and startPage. Optional maxItems truncates the plan and sets truncated true. At most 100,000 pages. Integer overflow is refused. This does not make requests or discover cursors.

A caller that guesses the last page from mental arithmetic will skip or duplicate rows.

Reliability

Integer overflow is PAGINATION_INVALID. PAGINATION_INVALID — trigger: more than 100,000 pages, overflow, or a missing mode; retryable: no; next: raise pageSize or lower the total.

Context footprint

Page descriptors only. A successful call costs 1 execution credit.

When to use it

When totalItems and pageSize are known and the next requests must be listed.

When the total is unknown or the API uses an opaque cursor.

Scope

Note

Calculates bounded page requests from a known total, page size and optional start or item cap.

Non-goals

Does not discover cursors
Does not make requests
Does not adapt rate limits

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

data-transformation

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input2 MB

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
mode	string	Yes	OFFSET_LIMIT uses startOffset; PAGE_NUMBER uses startPage and base.
totalItems	integer	Yes	Known total item count, including zero.
pageSize	integer	Yes	Positive page size used for every planned request.
startOffset	integer	No	First OFFSET_LIMIT offset. Omit it for 0.
startPage	integer	No	First PAGE_NUMBER page. Omit it for 1 when base is ONE, else 0.
base	string	No	PAGE_NUMBER numbering. Omit it for ONE.
maxItems	integer	No	Optional item cap that truncates the plan. Omit it to plan the full total.

Output schema

Field	Type	Required	Description
mode	string	Yes	Echoed OFFSET_LIMIT or PAGE_NUMBER.
pageCount	integer	Yes	How many pages were planned.
plannedItems	integer	Yes	How many items the plan covers.
truncated	boolean	Yes	True when maxItems stopped the plan before the total.
pages	array	Yes	Bounded array of 0 through 100000 ordered page-request descriptors.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"integration.pagination_plan","input":{"mode":"OFFSET_LIMIT","totalItems":5,"pageSize":2}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("integration.pagination_plan", {"pageSize":2,"mode":"OFFSET_LIMIT","totalItems":5});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
PAGINATION_INVALID	400	No	The request payload failed this skill's input validation.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not discover cursors
Does not make requests
Does not adapt rate limits
Unknown-total loops
Cursor-based pagination discovery

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "integration.pagination_plan",
  "input": {
    "pageSize": 2,
    "mode": "OFFSET_LIMIT",
    "totalItems": 5
  }
}

Examples

Five items at page size 2 yield three OFFSET_LIMIT pages

Inputjson

{
  "pageSize": 2,
  "mode": "OFFSET_LIMIT",
  "totalItems": 5
}

Expected outputjson

{
  "pages": [
    {
      "offset": 0,
      "limit": 2
    },
    {
      "offset": 2,
      "limit": 2
    },
    {
      "offset": 4,
      "limit": 1
    }
  ],
  "pageCount": 3,
  "mode": "OFFSET_LIMIT",
  "plannedItems": 5,
  "truncated": false
}

Tip

The last page has limit 1.

A zero total yields no pages and truncated false