Pagination and filtering | Pole Star APIs

List endpoints across Insights share one pagination model and one response envelope, so a single helper in your client works everywhere. Filter parameters vary by endpoint, and the reference page for each one is authoritative.

Pagination

Two query parameters, both optional.

Parameter	Default	Maximum	Notes
`limit`	`100`	`500`	Records per page
`offset`	`0`	None	Records to skip

The response carries a meta block telling you where you are and how much there is.

{
  "meta": {
    "limit": 100,
    "offset": 0,
    "total_count": 1043,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_timestamp": "2026-08-12T10:20:00Z"
  },
  "data": [ ]
}

Walk forward until offset + limit reaches or exceeds total_count.

Offsets are positional, not stable

Pagination is offset-based, not cursor-based, so we recalculate pages on each request. If records are created or removed while you are paging, an item can appear twice or be skipped.

For a consistent snapshot, narrow the query with a fixed time window instead of paging a live, unbounded set.

Knowing when to stop

Use total_count, not an empty page. It gives you the size of the result set up front, so you can size a job before you run it.

pages = ceil(total_count / limit)

If total_count is large enough to worry you, add filters instead of raising limit.

Parameter conventions

These hold across Insights, so you can predict them.

Convention	Detail
Naming	Query and body parameters are `snake_case`, always. Every Insights endpoint follows this convention.
Timestamps	ISO 8601, UTC, e.g. `2026-08-12T10:20:00Z`. Passing a local time or a bare date is the most common cause of a 400
Time windows	Where an endpoint accepts a range, it uses `timestamp_start` and `timestamp_end`. Inclusive lower bound. Where `timestamp_end` is optional, we treat a value in the future as the current time
Vessel identifiers	IMO is 7 digits. A 6- or 8-digit value returns a 422, not an empty result
Booleans	Lowercase `true` and `false`

Filtering

Filters are per endpoint, since what you can narrow depends on what the endpoint returns. The patterns you will meet most often:

By identifier

Most vessel endpoints take an IMO or MMSI. Zone and port endpoints take an id_type and id pair, so the same path serves several identifier schemes.

By time window

timestamp_start and timestamp_end. The narrowest filter available on most endpoints, and the one that most reduces response size.

By state

Subscription endpoints take active to separate live subscriptions from retired ones.

By vessel attribute

Analytics endpoints narrow by vessel type, vessel class, flag code or gross tonnage range. See the reference page for the accepted values.

An unrecognised filter value returns a 400 naming the offending parameter in field, instead of silently returning everything. See Errors & Status Codes.

Filters you will meet across the suite

Parameter	Narrows by
`timestamp_start`, `timestamp_end`	Time window
`event_type`	A specific event, such as `PORT_ARRIVAL` or `ZONE_ENTRY`
`zone_type`, `zone_sub_type`	Classes of area, such as `PORT`, `ANCHORAGE` or `EEZ`
`country_code`	ISO country code
`gap_threshold_gte`	Minimum AIS gap duration in hours
`sts_duration_gte`	Minimum ship-to-ship transfer duration in hours
`sts_type`	Transfer type, such as `CARGO` or `BUNKERING`
`port_sub_type`	Port category, such as port or anchorage area

The _gte suffix means "greater than or equal to", so gap_threshold_gte=6 returns gaps of six hours or longer. Not every parameter applies to every endpoint.

PurpleTRAC behaves differently

PurpleTRAC allows filtering and ordering only on an allowlist of fields, and rejects anything else instead of ignoring it.

{ "error": "The 'test' field does not allow filtering." }

{ "error": "No matching 'test' field for ordering on." }

It also supports order_by. Check the PurpleTRAC reference pages for the permitted fields on each resource.

Sorting

Where an endpoint supports sorting it exposes sort_by, taking asc or desc. The field it sorts on is fixed per endpoint. AIS reporting gaps, for example, sorts on the gap end timestamp and defaults to desc.

Sorting is not available everywhere. The reference page for each endpoint is authoritative.

Request Conventions

Naming, casing, units and coordinates in full.

Rate Limits & Quotas

What is enforced, and how to back off when you hit it.

Errors & Status Codes

Every code, body and retry rule.

Pagination & Filtering

Pagination#

Knowing when to stop#

Parameter conventions#

Filtering#

Filters you will meet across the suite#

PurpleTRAC behaves differently#

Sorting#

Related#