Skip to content
Hayonix

API reference · Dedicated endpoints

Get a deployment

GET/v1/endpoint-deployments/{deployment_id}
API keydedicated_endpoint:readProject
TypeScript
client.dedicatedEndpoints.getDeployment()
Python
client.dedicated_endpoints.get_deployment()
CLI
hayonix endpoints deployments show

The deployment with its status, traffic weight, replica counts and the reason of its last failed replica start.

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/endpoint-deployments/dpl_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

  • deployment_idstringrequired

    ID of the deployment

    ID with prefix dpl_

Response

200 EndpointDeployment — The deployment

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

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

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.