Skip to content
Hayonix

API reference · Dedicated endpoints

An endpoint's replicas, newest first

GET/v1/endpoints/{dedicated_endpoint_id}/replicas
API keydedicated_endpoint:readProjectPaginated
TypeScript
client.dedicatedEndpoints.listReplicas()
Python
client.dedicated_endpoints.list_replicas()
CLI
hayonix endpoints replicas

Live replicas by default; pass live=false to include removed ones with their termination reason (at most the 200 most recent).

Project API key (Authorization: Bearer sk_…), or a console session. Requires the dedicated_endpoint:read permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/replicas" \
  -H "Authorization: Bearer $API_KEY"

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.

Path parameters

  • dedicated_endpoint_idstringrequired

    ID of the dedicated endpoint

    ID with prefix ded_

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • liveboolean | string

    Only replicas not terminated (default true)

Response

200 a page of results — Replicas

  • The items of this page.

    Show 12 fields of data
    • objectstringrequired

      Always `endpoint_replica`: the type of this object

      One ofendpoint_replica

    • idstringrequired

      Unique ID (`rpl_…`)

      ID with prefix rpl_

    • deployment_idstring | nullrequired

      ID of the deployment

    • statestringrequired

      `starting`: downloading weights and loading (not billed). `ready`: passed the engine health check, taking traffic, billed per second. `draining`: leaving (no new requests).

      One ofstartingreadyunhealthydrainingterminated

    • hardwareobjectrequired

      The hardware the replica runs on

      Show 1 field of hardware
      • skustringrequired

        Hardware type code

    • node_idstring | nullrequired

      The node the replica is placed on (null until it is placed, and once removed)

    • ready_atstring (date-time) | nullrequired

      Time ready (ISO 8601, UTC)

    • health_messagestring | nullrequired

      The engine's health check failure that made the replica `unhealthy`; null once it is ready again, or if it never failed one

    • drain_reasonstring | nullrequired

      Why the replica is draining: `stopped` (the endpoint was stopped or deleted, or its deployment removed) or `scale_down` (demand fell); null when not draining

    • termination_reasonstring | nullrequired

      Why the replica was removed, for example `drained`, `startup_timeout` (not ready within the startup limit) or `unhealthy` (failing health checks for too long); null while it is live

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • terminated_atstring (date-time) | nullrequired

      Time terminated (ISO 8601, UTC)

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "object": "endpoint_replica",
      "id": "rpl_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "deployment_id": "string",
      "state": "starting",
      "hardware": {
        "sku": "string"
      },
      "node_id": "string",
      "ready_at": "2026-01-01T00:00:00.000Z",
      "health_message": "string",
      "drain_reason": "string",
      "termination_reason": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "terminated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.