Use pagination and filters

List endpoints can return more results than you want to handle in one response. Cursor pagination lets you move through those results safely, while filters narrow the result set.

Not every list endpoint supports the same filters. Use the endpoint reference for the exact parameters available on each endpoint.

How cursor pagination works

A paginated response includes a pagination object:

{
  "data": [],
  "pagination": {
    "next": "opaque-cursor",
    "size": 20
  }
}

If pagination.next contains a value, pass it back as the cursor query parameter. When it is null, you have reached the last page.

Cursors are opaque. Don’t edit, parse, or construct them yourself.

Request the first page

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?size=20" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

For GET /instances, size can be between 1 and 200. The default is 50.

Request the next page

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?size=20&cursor=opaque-cursor" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

Keep using the latest pagination.next value until it becomes null.

Filter instances

GET /instances supports filters for:

Filter	What it does
`status`	Filters by a lifecycle-status bucket. `running` also includes `CREATED`, `DEPLOYED`, and `STARTING`; `stopped` includes `STOPPING`; `terminated` includes `TERMINATING`; `errored` matches `ERRORED`.
`gpu_type`	Filters by GPU model.
`region`	Filters by region.
`date_range_begin`	Returns instances that started at or after a timestamp.
`date_range_end`	Returns instances that started at or before a timestamp.
`free_text_search`	Searches instance names and related searchable fields.

The accepted region values are:

UAE
FR
US

Example:

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?status=running&region=FR&size=20" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

Filter by date range

Date filters apply to started_at, not the time the instance record was created. An instance that has never started is excluded as soon as either date bound is used. Use ISO 8601 timestamps in UTC:

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?date_range_begin=2026-08-01T00:00:00Z&date_range_end=2026-08-10T23:59:59Z" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

Search by text

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?free_text_search=training-run" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

List presets by region

GET /presets is also cursor-paginated and can be filtered by supported catalogue fields such as region.

curl --request GET \
  --url "https://api.hivecompute.ai/v1/presets?region=FR&size=20" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

Common issues

Issue	What to check
Response is empty	Remove filters one at a time and confirm the account has matching resources.
API returns `400`	Check parameter names, allowed values, and date formats.
Next page repeats results	Use the latest cursor returned by the previous response.
Cursor no longer works	Request a fresh first page and use the new cursor.

Next step

Continue with Handle errors and rate limits.

Public API

API reference

Use pagination and filters

Request the first page

Request the next page

Filter instances

Filter by date range

Search by text

List presets by region

Common issues

Next step

​How cursor pagination works

​Request the first page

​Request the next page

​Filter instances

​Filter by date range

​Search by text

​List presets by region

​Common issues

​Next step

How cursor pagination works

Request the first page

Request the next page

Filter instances

Filter by date range

Search by text

List presets by region

Common issues

Next step