Lists: pagination, filtering, sorting, fields and expansion
Every list in the HIVE API (assets, signals, alarms, work orders, documents and the rest) works the same way. Learn it once. German version: Listen: Seitenwechsel, Filter, Sortierung, Felder und Erweiterung. The parameters of each list are in List parameters.
The response#
{
"object": "list",
"data": [ { "id": "alm_01m71xxn9ze26b4pq3dnxee9ms", "object": "alarm", "asset_id": "ast_01m71xxng7fzrvspnkgtw1t2kg", "expanded": {} } ],
"has_more": true,
"next_cursor": "c1.AQzIubxgQuAaae5Bh7r-gp9o...",
"total_count": null,
"total_count_is_lower_bound": null
}next_cursoris a string whenhas_moreistrueandnullwhen it isfalse, never anything else.- When
has_moreistruethe response also has a headerLink: <https://api.hive.clerktree.com/v1/alarms?cursor=...&limit=20&state=open>; rel="next": the same query with the new cursor. total_countandtotal_count_is_lower_boundarenullunless you sendcount=true(see below).
Paging: limit and cursor#
limitis 1 to 500, default 50. Anything else is400 invalid_requestwith the error codeinvalid_limit.- Send the
next_cursorof a page ascursorto get the page that follows. Repeat untilhas_moreisfalse. - There is no
offsetand nopage. Pagination is keyset based, so it stays fast on tables with millions of rows. - A cursor is opaque. Do not parse it, store it for longer than a day, or send it with a different query. It is bound to your tenant, the endpoint, the filters, the sort and the API version, and it expires 24 hours after it was issued. A cursor used with anything else, a damaged cursor, an expired cursor and a cursor of another tenant all give the same
400 invalid_cursor: start again without a cursor. - The same cursor on unchanged data returns the same page.
The consistency promise#
A walk over a set that does not change returns every row exactly once. While rows are added, changed and deleted:
- a row whose sort values do not change is returned at most once and never skipped;
- a row whose sort key changes during the walk may be returned twice or missed;
- a row deleted between two pages causes no error; the walk continues from the position in the cursor.
If you need a complete copy of changing data, use the change feeds and exports, not a long list walk.
Filters#
field=value is equality. field[operator]=value uses an operator. Several parameters combine with AND; there is no OR (use in, or two requests). Each list declares which fields are filterable and with which operators (List parameters).
| Operator | Meaning | Applies to |
|---|---|---|
eq (the bare form) | equal | all types |
ne | not equal | all types |
gt, gte, lt, lte | greater, greater or equal, less, less or equal | numbers, timestamps, dates |
in, nin | in / not in a comma separated list of at most 100 values | strings, enums, numbers, references |
contains, prefix | contains / starts with, case-insensitive | fields declared text-searchable |
is_null | true finds empty values, false non-empty values | all types |
Values are typed:
- timestamps: RFC 3339 with an offset, normalised to UTC:
2026-11-09T00:00:00Zor2026-11-09T01:00:00+01:00. A date alone is refused. - dates (fields ending in
_on):YYYY-MM-DD. - numbers: plain decimals; quantities are filtered by their numeric value in the stored unit (documented per field).
- booleans:
trueorfalse. References: the ID with its prefix (ast_...). Enumerations: one of the documented values. inandnin:state[in]=open,acknowledgedorstate[in]=open&state[in]=acknowledged. A value cannot contain a comma.- A comparison never matches an empty value:
due_on[ne]=2026-11-20does not return work orders without a due date; usedue_on[is_null]=true.
At most 5 filters, 100 values in an in list, 3 sort fields and 3 expansions per request. A filter on a field that is not declared filterable, an operator not allowed for the field, a value of the wrong type and a parameter the list does not know are rejected with 400 invalid_request; they are never ignored. The error items carry the parameter and one of the codes invalid_filter_field, invalid_filter_operator, invalid_type, invalid_enum, too_many_items, unknown_field.
Examples (Musterwerk):
GET /v1/alarms?state=open&asset_id[in]=ast_01m71xxng7fzrvspnkgtw1t2kg,ast_01m71xxpcwfz1snpsm3pqdqrjc&sort=-raised_at&expand=asset&limit=20
GET /v1/work-orders?created_at[gte]=2026-11-09T00:00:00Z&title[contains]=bearing&fields=id,key,title,state
GET /v1/assets?asset_type_id[is_null]=trueFilter values are never written to our logs; only the field names and operators are.
Sort#
sort=raised_at,-key: a comma separated list of up to 3 sortable fields, - for descending. The server appends id as the last key so that the order is total; it takes the direction of the last field you gave. The default is -id (newest first) unless the list documents another default. A field that is not sortable, a repeated field, id anywhere but last, or more than 3 fields is 400 invalid_sort_field. Empty values sort last when ascending and first when descending.
Fields: fields#
fields=key,name returns only those top-level fields plus id and object. One dot level selects part of an object or of each object of an array: fields=key,external_refs.system. An unknown name is 400 invalid_field_selection. A list that has expansions always keeps the member expanded.
Expansion: expand#
expand=asset adds the referenced objects under expanded.asset and keeps the asset_id field. Only names the list declares are allowed, at most 3, one level deep (asset.parent is refused). Without expand the member is "expanded": {}.
An expansion is a read with your permissions: an object you may not read, or that does not exist, is null in expanded, never an error and never data. Select fields of an expanded object with fields[asset]=key,name.
Counting: count=true#
count=true adds total_count: exact up to 10,000. Above that total_count is 10000 and total_count_is_lower_bound is true. Without count=true nothing is counted. If the count takes too long the page is still returned and total_count is null.
Errors#
| Situation | Response |
|---|---|
| Bad parameter | 400 invalid_request, one item per problem in errors[] with parameter |
| Cursor invalid, expired, or used with another query, tenant, endpoint or version | 400 invalid_cursor (always the same body) |
| The database needs more than 2 seconds for a page | 504 timeout, no partial data; narrow the filter and retry |