HIVE Docs
Explore HIVE

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#

JSON
{
  "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
}

Paging: limit and cursor#

The consistency promise#

A walk over a set that does not change returns every row exactly once. While rows are added, changed and deleted:

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).

OperatorMeaningApplies to
eq (the bare form)equalall types
nenot equalall types
gt, gte, lt, ltegreater, greater or equal, less, less or equalnumbers, timestamps, dates
in, ninin / not in a comma separated list of at most 100 valuesstrings, enums, numbers, references
contains, prefixcontains / starts with, case-insensitivefields declared text-searchable
is_nulltrue finds empty values, false non-empty valuesall types

Values are typed:

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):

Code
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]=true

Filter 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#

SituationResponse
Bad parameter400 invalid_request, one item per problem in errors[] with parameter
Cursor invalid, expired, or used with another query, tenant, endpoint or version400 invalid_cursor (always the same body)
The database needs more than 2 seconds for a page504 timeout, no partial data; narrow the filter and retry