Server fleet with current readings

GET

/servers

const url = 'https://api.flotera.com/api/v1/servers?limit=50&presence=online&marketplace=vast';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.flotera.com/api/v1/servers?limit=50&presence=online&marketplace=vast' \
  --header 'Authorization: Bearer <token>'

Returns one page of servers and their latest readings, ordered by ID. Use next_cursor to request the next page.

While the account is frozen, readings is null and gpus is empty. Presence, last_seen_at, gpu_count and gpu_model remain current. The same rule applies to the individual server endpoint.

Authorizations

integrationToken

Parameters

Query Parameters

cursor

string

>= 1 characters <= 512 characters

Pass next_cursor from the previous response unchanged. An invalid cursor returns 422.

limit

integer

default: 50 >= 1 <= 200

Page size.

presence

Agent presence: suspect after 60 seconds without a heartbeat, offline after 300. Telemetry alone does not prove presence and does not make a machine online.

string

Allowed values: online suspect offline

Filter by agent presence.

marketplace

string

Allowed values: vast clore quickpod

Filter by the active marketplace — the one named in the machine’s marketplace field: where it is listed, otherwise the link seen most recently. A machine linked to several marketplaces matches only its active one. Any other value is refused with 422.

Header Parameters

If-None-Match

string

<= 256 characters

Return 304 Not Modified if the entity tag has not changed.

Responses

200

One page of the fleet from a consistent snapshot.

application/json

object

generated_at

required

When the snapshot was computed.

string format: date-time

data_as_of

required

Time through which source data is included in this response.

string format: date-time

version

required

Response format version.

integer

>= 1

stale

required

True when this response contains previously collected data awaiting a refresh.

boolean

stale_reason

string | null

<= 256 characters

items

required

Array<object>

<= 200 items

Server status, hardware readings and marketplace information. Earnings and billing are unavailable through this API.

object

required

UUID (v7 for new entities; v4 is accepted).

string format: uuid

name

required

string

<= 255 characters

hostname

string | null

<= 255 characters

presence

required

Agent presence: suspect after 60 seconds without a heartbeat, offline after 300. Telemetry alone does not prove presence and does not make a machine online.

string

Allowed values: online suspect offline

last_seen_at

Last heartbeat received from the agent.

string | null format: date-time

agent_version

Null until an agent has registered on the machine.

string | null

<= 64 characters

gpu_count

required

integer

gpu_model

Model of the cards, when they are all the same.

string | null

<= 128 characters

group_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

tags

required

Labels of the form key or key:value.

Array<string>

<= 64 items

maintenance_since

Set while the owner keeps the machine in maintenance.

string | null format: date-time

marketplace

One of:

object
null

The machine’s active marketplace link.

object

name

required

Marketplace identifier, for example vast or clore. The marketplace filter of the server list selects by this value.

string

<= 64 characters

listing

One of:

object
null

The machine’s offer on the marketplace. Present only while the machine is listed; null — not listed.

object

state

required

rented — the machine is currently taken by a renter; expired — the fixed-offer window has ended; listed — listed and free.

string

Allowed values: listed rented expired

price_usd_per_gpu_hour

Offer price per GPU-hour.

string | null

/^-?[0-9]+(\.[0-9]{1,6})?$/

spot_usd_per_gpu_hour

The floor bid, if the marketplace supports one.

string | null

/^-?[0-9]+(\.[0-9]{1,6})?$/

expires_at

End of the fixed-offer window; null for a rolling one.

string | null format: date-time

rolling_seconds

Length of the rolling window, when the offer uses one.

integer | null

readings

One of:

object
null

Current state of the host — the last accepted reading, not history. Absent entirely while the agent has never reported.

object

observed_at

required

The moment of the host reading itself, not of the response.

string | null format: date-time

stale

required

True when the reading is older than 300 seconds or missing.

boolean

cpu_usage_pct

number | null

<= 100

ram_used_mb

integer | null

ram_total_mb

integer | null

disk_used_mb

integer | null

disk_total_mb

integer | null

net_rx_kbs

Current network receive rate.

number | null

net_tx_kbs

Current network transmit rate.

number | null

power_w

Draw of the whole host, GPUs included. Do not add GPU power on top — that would count it twice.

number | null

uptime_s

integer | null

gpu_utilization_pct_avg

number | null

gpu_temperature_c_max

number | null

gpu_fan_pct_max

number | null

gpu_observed_at

Timestamp of the oldest GPU reading used in the aggregates. Null if any GPU reading has no timestamp.

string | null format: date-time

gpu_stale

required

The aggregates are older than 300 seconds, there are no cards, or the age is unknown.

boolean

gpus

Current state of the cards; empty while there are no readings — and while the account is frozen.

Array<object>

<= 128 items

Current state of one card.

object

index

required

Position of the card in the machine.

integer

observed_at

required

Timestamp of this GPU’s reading. It is independent of the host timestamp.

string | null format: date-time

stale

required

True when this GPU’s reading is older than 300 seconds or missing. Check this flag even when the host readings block is absent.

boolean

model

string | null

<= 128 characters

temperature_c

number | null

hotspot_temperature_c

number | null

memory_temperature_c

number | null

fan_pct

number | null

utilization_pct

number | null

memory_used_mb

integer | null

power_w

number | null

power_limit_w

number | null

next_cursor

required

Cursor of the next page; null — there are no more pages.

string | null

>= 1 characters <= 512 characters

Example

{
  "generated_at": "2026-09-10T10:15:30.123456Z",
  "data_as_of": "2026-09-10T10:15:30.123456Z",
  "items": [
    {
      "presence": "online",
      "marketplace": {
        "listing": {
          "state": "listed"
        }
      }
    }
  ]
}

Headers

ETag

string

<= 256 characters

Entity tag of the returned snapshot.

304

The snapshot has not changed since the presented entity tag.

Headers

ETag

string

<= 256 characters

Entity tag of the returned snapshot.

401

The token is missing, expired, revoked or issued for another purpose.

application/problem+json

RFC 9457 error response with a stable machine-readable code.

object

type

required

https://flotera.com/problems/<code>.

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Use this code to identify the error and decide whether to retry or correct the request.

string

Allowed values: unauthorized forbidden not_found method_not_allowed validation_failed rate_limited feature_not_entitled account_frozen tenant_suspended temporarily_unavailable internal_error

detail

string | null

<= 2048 characters

instance

string | null

<= 512 characters

request_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

Example

{
  "code": "unauthorized"
}

403

The token is genuine, but this operation is not available to it.

application/problem+json

RFC 9457 error response with a stable machine-readable code.

object

type

required

https://flotera.com/problems/<code>.

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Use this code to identify the error and decide whether to retry or correct the request.

string

Allowed values: unauthorized forbidden not_found method_not_allowed validation_failed rate_limited feature_not_entitled account_frozen tenant_suspended temporarily_unavailable internal_error

detail

string | null

<= 2048 characters

instance

string | null

<= 512 characters

request_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

Example

{
  "code": "unauthorized"
}

405

This path does not support the requested HTTP method. Check the Allow header for supported methods.

application/problem+json

RFC 9457 error response with a stable machine-readable code.

object

type

required

https://flotera.com/problems/<code>.

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Use this code to identify the error and decide whether to retry or correct the request.

string

Allowed values: unauthorized forbidden not_found method_not_allowed validation_failed rate_limited feature_not_entitled account_frozen tenant_suspended temporarily_unavailable internal_error

detail

string | null

<= 2048 characters

instance

string | null

<= 512 characters

request_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

Example

{
  "code": "unauthorized"
}

Headers

Allow

string

Methods this path accepts.

422

Request parameters failed validation.

application/problem+json

RFC 9457 error response with a stable machine-readable code.

object

type

required

https://flotera.com/problems/<code>.

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Use this code to identify the error and decide whether to retry or correct the request.

string

Allowed values: unauthorized forbidden not_found method_not_allowed validation_failed rate_limited feature_not_entitled account_frozen tenant_suspended temporarily_unavailable internal_error

detail

string | null

<= 2048 characters

instance

string | null

<= 512 characters

request_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

Example

{
  "code": "unauthorized"
}

429

Too many requests or failed authentication attempts. Check the token and wait for Retry-After seconds before retrying.

application/problem+json

RFC 9457 error response with a stable machine-readable code.

object

type

required

https://flotera.com/problems/<code>.

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Use this code to identify the error and decide whether to retry or correct the request.

string

Allowed values: unauthorized forbidden not_found method_not_allowed validation_failed rate_limited feature_not_entitled account_frozen tenant_suspended temporarily_unavailable internal_error

detail

string | null

<= 2048 characters

instance

string | null

<= 512 characters

request_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

Example

{
  "code": "unauthorized"
}

Headers

Retry-After

integer

Seconds to wait before retrying.

503

The data source is temporarily unavailable.

application/problem+json

RFC 9457 error response with a stable machine-readable code.

object

type

required

https://flotera.com/problems/<code>.

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Use this code to identify the error and decide whether to retry or correct the request.

string

Allowed values: unauthorized forbidden not_found method_not_allowed validation_failed rate_limited feature_not_entitled account_frozen tenant_suspended temporarily_unavailable internal_error

detail

string | null

<= 2048 characters

instance

string | null

<= 512 characters

request_id

One of:

string
null

UUID (v7 for new entities; v4 is accepted).

string format: uuid

Example

{
  "code": "unauthorized"
}

Headers

Retry-After

integer

Seconds to wait before retrying.