Skip to main content

List Available Machines

Endpoint Description​

GET /clore/v1/machines

Retrieves a list of machines currently available for deployment. This endpoint supports filtering and pagination to help refine the results based on specific criteria.

Using the filter Query Parameter​

The filter query parameter allows you to refine your search for machines based on specific criteria. This powerful feature supports a range of conditions to help you locate exactly what you need.

Available Filters​

  • gpu_name: Filter machines by the name of GPU installed.
  • memory_size: Specify the desired memory size to find machines that match or exceed this specification in GB.
  • cpu_name: Filter based on the CPU name.
  • cpu_cores: Filter based on the number of CPU cores.
  • storage_size: Search for machines based on storage size in GB.
  • machine_id: Retrieve a specific machine by its unique identifier.
  • machine_status: Filter machines based on their current status, such as available or unavailable.

Using filter in Your API Call​

Include the filter parameter in your API request as a query string, URL-encoded if necessary:

/clore/v1/machines?filter=gpu_name:Nvidia%20RTX%203090,memory_size:24GB

This request retrieves machines equipped with an Nvidia RTX 3090 GPU and at least 24GB of RAM.

Tips for Effective Filtering​

  • Be Specific: Use precise criteria to narrow down your results effectively.
  • URL Encoding: Ensure complex queries are URL-encoded to avoid issues with special characters.
  • Check Availability: For attributes like machine.status, consider filtering for available machines to focus on ready-to-use resources.

Success Response​

Status Code: 200 OK

Response Body Description​

The response body for the "List Available Machines" endpoint provides a comprehensive overview of the machines available for deployment. Below is a detailed description of each field within the response.

Response Fields​

  • total: Integer indicating the total number of machines matching the query parameters.
  • current_page: Integer representing the current page number in the paginated result set.
  • page_size: Integer showing the number of items per page in the response.
  • machines: An array of machine objects, each containing detailed information about a specific machine.

Machine Prices​

The machine_prices field is an array that provides detailed pricing options set by the rig owner for renting a machine. Each entry in this array represents a specific price that the rig owner is willing to accept, allowing renters to choose from multiple pricing options. This flexibility ensures that renters can select a price that best suits their budget and requirements. Each price entry includes a unique identifier to guarantee that the renter will be charged the exact price they saw at the time of listing, even if the machine owner updates the price later.

Machine Price Object Fields​

  • id: A unique identifier for the price entry. This ID ensures that the price remains consistent from the time it is listed until the renter confirms the rental, protecting against price changes.
  • amount: The amount of the price in the specified currency.
  • currency: The currency in which the price is listed. This can be a standard currency like USD (United States Dollar) or a cryptocurrency like BTC (Bitcoin).

Machine Object Fields​

  • status: String indicating the availability status of the machine ("available" for machines ready to be deployed).
  • metadata: Object containing metadata about the machine.
    • machine_id: Unique identifier for the machine.
    • geo_location: Object containing geographical location information of the machine.
      • country: Country where the machine is located.
      • city: City where the machine is located.
    • cuda_version: The version of CUDA installed on the machine.
  • hardware_specs: Object detailing the hardware specifications of the machine.
    • cpu: Object containing information about the CPU.
      • model: CPU model.
      • cpu_arch: CPU architecture (e.g., "amd64").
      • cores: Number of CPU cores.
      • threads: Number of CPU threads.
      • base_clock: Base clock speed in MHz.
      • boost_clock: Boost clock speed in MHz.
    • memory: Object detailing the machine's memory specs.
      • total_memory: Total memory in GB.
      • memory_required: Minimum memory required in GB for the deployment.
    • storage: Object containing storage information.
      • disk_space_available: Available disk space in GB.
      • disk_type: Type of storage disk (e.g., "ssd").
      • disk_name: Identifier for the disk.
    • gpus: Array of objects, each representing a GPU available on the machine.
      • id: Unique identifier for the GPU.
      • name: Model name of the GPU.
      • memory: Memory available on the GPU in GB.
      • cuda_cores: Number of CUDA cores.
      • tensor_cores: Number of Tensor cores.
      • flops: Floating-point operations per second in TFLOPs.
  • network_info: Object with network-related specifications.
    • bandwidth: Available bandwidth in Mbps.
  • machine_prices: Array of objects representing the different pricing options set by the rig owner.
    • id: Unique identifier for the price entry, ensuring consistency from listing to rental.
    • amount: The amount of the price in the specified currency.
    • currency: The currency in which the price is listed, such as USD or BTC.

Example of Machine Prices​

"machine_prices": [
    {
        "id": "5b10ce4d-9772-4487-bcc0-c7440e633370",
        "amount": "1",
        "currency": "BTC"
    },
    {
        "id": "3f189ae6-f831-4509-a018-1bce5cde48ee",
        "amount": "5",
        "currency": "USD"
    }
]

In this example:

  • The first price option is 1 BTC, identified by the unique ID 5b10ce4d-9772-4487-bcc0-c7440e633370.
  • The second price option is 5 USD, identified by the unique ID 3f189ae6-f831-4509-a018-1bce5cde48ee.

Rig owners can set multiple prices to provide renters with various options. This system ensures transparency and fairness in the pricing mechanism, as renters can be assured they will pay the price they agreed to at the time of booking.

Example Response Body​

{
  "total": 1,
  "current_page": 1,
  "page_size": 1,
  "machines": [
    {
      "status": "available",
      "machine_prices": [
          {
              "id": "5b10ce4d-9772-4487-bcc0-c7440e633370",
              "amount": "1",
              "currency": "BTC"
          },
          {
              "id": "3f189ae6-f831-4509-a018-1bce5cde48ee",
              "amount": "5",
              "currency": "USD"
          }
      ],
      "metadata": {
        "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
        "geo_location": {
          "country": "USA",
          "city": "San Francisco",
        },
        "cuda_version": "12.1"
      },
      "hardware_specs": {
        "cpu": {
          "model": "AMD EPYC 7532 32-Core Processor",
          "cpu_arch": "amd64",
          "cores": 10,
          "threads": 20,
          "base_clock": 3700,
          "boost_clock": 5300,
        },
        "memory": {
          "total_memory": 64,
          "memory_required": 1,
        },
        "storage": {
          "disk_space_available": 1,
          "disk_type": "ssd",
          "disk_name": "nvme",
        },
        "gpus": [
          {
            "id": "e37d339d-f1dd-4587-88e7-a8ce76ce1086",
            "name": "Nvidia GeForce 3090",
            "memory": 24,
            "cuda_cores": 10496,
            "tensor_cores": 328,
            "flops": 36,
          },
          {
            "id": "d58f2c8d-754f-4974-a952-fe277adfce95",
            "name": "Nvidia GeForce 3070",
            "memory": 8,
            "cuda_cores": 5000,
            "tensor_cores": 140,
            "flops": 10,
          }
        ]
      },
      "network_info": {
        "bandwidth": 1000
      }
    }
  ]
}

HTTP Status Codes​

The "List Available Machines" endpoint may return the following HTTP status codes based on the outcome of the request:

  • 200 OK: The request was successful, and the response body contains the list of available machines, along with details specified in the documentation.
  • 400 Bad Request: The server could not understand the request due to an invalid syntax. This status is typically returned if the query parameters are formatted incorrectly or include unsupported filters.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource. This status indicates that the client must authenticate themselves to get the requested response.
  • 403 Forbidden: The server understood the request but refuses to authorize it. This typically means the requester doesn't have permission to access the list of machines.
  • 404 Not Found: The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error message when no specific message is suitable.

Example cURL Request​

curl -X GET "https://api.hiveon.ai/clore/v1/machines?page=1&page_size=10&filter=gpu:GeForce%203090" \
     -H "Accept: application/json"

This response contains a list of machines, each with detailed information about its hardware specifications, network information, and current availability status. Utilize the filter, page, and page_size query parameters to navigate through the available machines efficiently.