Skip to content
Hayonix

API reference · Dedicated endpoints

List dedicated endpoints in the project, newest first

GET/v1/endpoints
API keydedicated_endpoint:readProjectPaginated
TypeScript
client.dedicatedEndpoints.list()
Python
client.dedicated_endpoints.list()
CLI
hayonix endpoints list

Each endpoint comes with its deployments, their replica counts and the endpoint's current status. Deleted endpoints are not listed.

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" \
  -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.

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

Response

200 a page of results — A page of endpoints

  • The items of this page.

    Show 19 fields of data
    • objectstringrequired

      Always `dedicated_endpoint`: the type of this object

      One ofdedicated_endpoint

    • idstringrequired

      Unique ID (`ded_…`)

      ID with prefix ded_

    • org_idstringrequired

      Organization it belongs to

      ID with prefix org_

    • project_idstringrequired

      Project it belongs to

      ID with prefix prj_

    • namestringrequired

      Its name

    • display_namestring | nullrequired

      Name to show people

    • modelstringrequired

      The model ID to send in OpenAI-compatible requests

    • typestringrequired

      What the served model does

      One ofchatcompletionembeddingrerank

    • context_lengthinteger | nullrequired

      Context length in tokens of the served model; null when not known

    • statusstringrequired

      `stopped`: no replicas. `stopping`: stopped, replicas still being removed. `starting`: running, but no deployment with traffic has a ready replica yet. `serving`: every deployment with traffic has at least its minimum replicas ready. `degraded`: serving, but some deployment with traffic has fewer ready replicas than its minimum (or none). `failed`: no deployment with traffic is ready and at least one has stopped starting replicas after repeated failures.

      One ofstoppedstoppingstartingservingdegradedfailed

    • desired_statestringrequired

      What you asked for: `running` after create (unless `start` was false) or start, `stopped` after stop or an automatic stop (see `stop_reason`)

      One ofrunningstopped

    • stop_reasonstring | nullrequired

      `requested`, `inactivity`, `billing:<reason>` or `deleted`

    • inactivity_timeout_secondsintegerrequired

      The endpoint stops after this many seconds without a request (0: never)

    • last_request_atstring (date-time) | nullrequired

      Time last request (ISO 8601, UTC)

    • started_atstring (date-time) | nullrequired

      When it started (null until then) (ISO 8601, UTC)

    • stopped_atstring (date-time) | nullrequired

      Time stopped (ISO 8601, UTC)

    • deploymentsarray of EndpointDeploymentrequired

      The live deployments of the endpoint, oldest first

      Show 19 fields of deployments
      • objectstringrequired

        Always `endpoint_deployment`: the type of this object

        One ofendpoint_deployment

      • idstringrequired

        Unique ID (`dpl_…`)

        ID with prefix dpl_

      • endpoint_idstringrequired

        ID of the endpoint

        ID with prefix ded_

      • namestringrequired

        Its name

      • statusstringrequired

        `ready`: at least min_replicas ready. `degraded`: some, fewer. `failed`: stopped starting replicas after repeated failures (see last_failure); update or restart to retry.

        One ofstoppedstartingreadydegradedfailed

      • modelobjectrequired

        Model ID (`publisher/name`)

        Show 6 fields of model
        • catalog_model_idstring | nullrequired

          ID of the catalog model

        • repositorystringrequired

          Where the weights come from: a Hugging Face repository `<owner>/<name>`, or a `fine-tuned://` URI for a fine-tuned model

        • filestring | nullrequired

          The weights file or quantisation tag chosen in the repository; null when the whole repository is used

        • revisionstring | nullrequired

          Branch, tag or commit; null for the repository's default branch

        • token_secret_idstring | nullrequired

          ID of the token secret

        • fine_tuned_model_idstring | nullrequired

          Set when the deployment serves a fine-tuned model (then `repository` is its `fine-tuned://` URI)

      • engineServingEnginerequired

        `llama_cpp`: GGUF chat and completion models (CPU or GPU). `tei`: embedding and rerank models. `vllm`: chat, completion and embedding models on GPUs.

        One ofllama_cppteivllm

      • hardwareobjectrequired

        The hardware each replica runs on and its GPUs per replica

        Show 2 fields of hardware
        • skustringrequired

          Hardware type code

        • gpu_countintegerrequired

          Number of GPUs

      • regionstringrequired

        Region code

      • engine_optionsobjectrequired

        Engine settings chosen for this deployment

        Show 2 fields of engine_options
        • context_lengthinteger | nullrequired

          Context length in tokens per request; null: the engine's default

        • parallelinteger | nullrequired

          Requests one replica runs at once; null: the engine's default

      • disk_gbintegerrequired

        Disk per replica for the weights, in GB

      • min_replicasintegerrequired

        Fewest replicas kept running while the endpoint runs

      • max_replicasintegerrequired

        Most replicas the autoscaler may run

      • autoscalingobjectrequired

        How the replica count follows demand

        Show 1 field of autoscaling
        • target_concurrencyintegerrequired

          Concurrent requests per replica the autoscaler aims for: replicas = ceil(concurrency / target), between min and max

      • traffic_weightintegerrequired

        Percentage of the endpoint's requests sent to this deployment (0–100; the weights of an endpoint's deployments sum to 100)

      • replicasReplicaCountsrequired
        Show 4 fields of replicas
        • readyintegerrequired

          Replicas taking traffic

        • startingintegerrequired

          Replicas downloading weights or loading the model

        • unhealthyintegerrequired

          Replicas that were ready but are failing health checks (no traffic)

        • drainingintegerrequired

          Replicas finishing their requests before removal

      • last_failurestring | nullrequired

        Why the most recent replica failed to start; null when there is none. Cleared on a start of the endpoint or an update of the deployment.

      • created_atstring (date-time)required

        When it was created (ISO 8601, UTC)

      • updated_atstring (date-time)required

        When it last changed (ISO 8601, UTC)

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • updated_atstring (date-time)required

      When it last changed (ISO 8601, UTC)

  • next_cursorstring | nullrequired

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

Example response
Example response
{
  "data": [
    {
      "object": "dedicated_endpoint",
      "id": "ded_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "name": "string",
      "display_name": "string",
      "model": "acme/support-bot",
      "type": "chat",
      "context_length": 1,
      "status": "stopped",
      "desired_state": "running",
      "stop_reason": "string",
      "inactivity_timeout_seconds": 1,
      "last_request_at": "2026-01-01T00:00:00.000Z",
      "started_at": "2026-01-01T00:00:00.000Z",
      "stopped_at": "2026-01-01T00:00:00.000Z",
      "deployments": [
        {
          "object": "endpoint_deployment",
          "id": "dpl_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "endpoint_id": "ded_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "name": "string",
          "status": "stopped",
          "model": {
            "catalog_model_id": "string",
            "repository": "string",
            "file": "string",
            "revision": "string",
            "token_secret_id": "string",
            "fine_tuned_model_id": "string"
          },
          "engine": "llama_cpp",
          "hardware": {
            "sku": "string",
            "gpu_count": 1
          },
          "region": "string",
          "engine_options": {
            "context_length": 1,
            "parallel": 1
          },
          "disk_gb": 1,
          "min_replicas": 1,
          "max_replicas": 1,
          "autoscaling": {
            "target_concurrency": 1
          },
          "traffic_weight": 1,
          "replicas": {
            "ready": 1,
            "starting": 1,
            "unhealthy": 1,
            "draining": 1
          },
          "last_failure": "string",
          "created_at": "2026-01-01T00:00:00.000Z",
          "updated_at": "2026-01-01T00:00:00.000Z"
        }
      ],
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_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.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.