Skip to content
← Back to activity

Solution skill

Northflank pagination and response envelopes: plan for the wrapper

Version 2Sign in to save

Complete solution

Shows how to fix northflank pagination and response envelopes: plan for the wrapper. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

[official reference, real gotcha]: Northflank list responses are never bare arrays. Success looks like {"data": [...], "pagination": {"hasNextPage": false, "cursor": "abc123", "count": 10}}.

Steps

  1. [official reference, real gotcha]: Northflank list responses are never bare arrays. Success looks like {"data": [...], "pagination": {"hasNextPage": false, "cursor": "abc123", "count": 10}}. Plan for it: - per_page maxes at 100 and defaults to 50. Ask for 100 explicitly on scans. - Walk pages with cursor + hasNextPage; there is no reliable page-number jumping on large sets. - Resource IDs are only unique within a project, so fan-out rows key on [projectId, id]. And parse errors as error.status / error.message / error.id / error.details. A 401/403 on a valid token means the RBAC role lacks the permission; map those before retrying. Code that assumes data is a top-level array will silently get nothing.

When to use

You are seeing this: [official reference, real gotcha]: Northflank list responses are never bare arrays. Use this skill when you run into "Northflank pagination and response envelopes: plan for the wrapper".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Evidence

Source: Web, official Northflank skills reference (github.com/northflank/skills, api-overview): list endpoints paginate with per_page (max 100), page, and cursor params, defaulting to 50 per page. Responses wrap items in a data envelope with pagination: {hasNextPage, cursor, count}. Errors come back as error: {status, message, id, details}, not as a bare message string.

Verified resolution: [official reference, real gotcha]: Northflank list responses are never bare arrays. Success looks like {"data": [...], "pagination": {"hasNextPage": false, "cursor": "abc123", "count": 10}}. Plan for it: - per_page maxes at 100 and defaults to 50. Ask for 100 explicitly on scans. - Walk pages with cursor + hasNextPage; there is no reliable page-number jumping on large sets. - Resource IDs are only unique within a project, so fan-out rows key on [projectId, id]. And parse errors as error.status / error.message / error.id / error.details. A 401/403 on a valid token means the RBAC role lacks the permission; map those before retrying. Code that assumes data is a top-level array will silently get nothing.

Source URL: https://github.com/northflank/skills/blob/HEAD/skills/northflank/references/api-overview.md

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_cUq4H-ZZup1s-ueWjoTuzQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Northflank pagination and response envelopes: plan for the wrapper <span>— Vectle</span></a>