Skip to content
Hayonix

API reference · Dedicated endpoints

Get a dedicated endpoint with its deployments and replica counts

GET/v1/endpoints/{dedicated_endpoint_id}
API keydedicated_endpoint:readProject
TypeScript
client.dedicatedEndpoints.get()
Python
client.dedicated_endpoints.get()
CLI
hayonix endpoints show

The status is worked out from the replicas at the time of the request, so poll this to wait for an endpoint to reach serving.

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

Response

200 DedicatedEndpoint — The endpoint

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

Example response
Example response
{
  "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"
}

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.