Endpoint pagination inconsistency with non-positive pageSize values

Question

Since Portainer 2.12, the /api/endpoints endpoint supports pagination via the page and pageSize query parameters. While positive integers correctly limit the result set, the API's behavior when encountering non-positive integers remains undefined.When an automation script passes a pageSize of zero or a negative value, the API does not return a 400 Bad Request error. Instead, the response either returns an empty array or the entire dataset depending on the internal logic. This lack of predictability creates risks for scripts that dynamically calculate bounds for large environments.Does the API return an empty set or the full endpoint list when pageSize is set to zero?Is there a functional difference in the response between a zero and a negative pageSize value?

Tasadduq Burney · Answer

Answer
For pageSize=0 the API may return either an empty array or the full list of endpoints; the same unpredictability applies to negative values. No 400 Bad Request is returned.
Confirmed facts

The /api/endpoints endpoint has accepted page and pageSize query parameters since Portainer 2.12.
When pageSize is a positive integer, the result set is correctly limited.
The API documentation does not define behavior for zero or negative pageSize, and no validation error is emitted.

Likely explanation
Internally the pagination value is passed straight to the data‑store query (e.g., SQL LIMIT or an equivalent offset‑limit clause). A limit of zero yields an empty result set, while a negative limit is often treated as “no limit” or is clamped to a default, which explains why the response can swing between empty and full.
Steps to handle this in automation

Validate pageSize client‑side: reject values < 1 before calling the API.
If you need to probe the total number of endpoints, request pageSize=1 and compare the returned count with the total header (if provided) or make a second request with a large safe limit.
Never rely on zero or negative values to obtain an empty set or a full dump; treat them as programmer errors.
Test the behavior in a non‑production instance of the exact Portainer version you run, using the commands below.

# Example curl calls (adjust URL and auth token)
curl -s -H "X-Api-Key: $TOKEN" \
  "https://portainer.example.com/api/endpoints?page=1&pageSize=1"   # baseline
curl -s -H "X-Api-Key: $TOKEN" \
  "https://portainer.example.com/api/endpoints?page=1&pageSize=0"   # observe response
curl -s -H "X-Api-Key: $TOKEN" \
  "https://portainer.example.com/api/endpoints?page=1&pageSize=-1"  # observe response

Record the HTTP status, response body length, and any total‑count header. If the body length changes between the zero and negative calls, you have confirmed a functional difference; otherwise the backend treats both as the same case.

Endpoint pagination inconsistency with non-positive pageSize values

1 answer

Answer

Confirmed facts

Likely explanation

Steps to handle this in automation

Your perspective belongs here.

1 question comment

Status code cannot detect invalid pagination