> ## Documentation Index
> Fetch the complete documentation index at: https://io.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Device Object Reference

> Defines the structure, attributes, and metrics of a Device within the IO Network. Includes details on hardware specs, network performance, compliance, and job history used for monitoring and rewards calculation.

### Device Object

The **Device Object** represents a compute node within the IO Network, typically a machine or worker running one or more GPUs. It provides the foundational schema for describing devices that contribute compute power to the distributed network.

Each device entry captures details about its hardware, performance metrics, network characteristics, geographic location, and SOC 2 compliance. This object also tracks job-level details such as compute minutes, uptime, and earnings, this allows for transparent performance analytics, availability tracking, and compensation calculation.

***

## Structure Overview

A **Device** includes:

* **Identification** – Unique ID, hardware name, and quantity
* **Performance Metrics** – Uptime, speed, and availability stats
* **Geographic Info** – Location name, ISO code, and country icon
* **Compliance** – SOC 2 certification flag
* **Job History** – Records of compute jobs, earnings, and status

***

## Core Attributes

<ParamField path="device_id" type="string" required>
  The unique identifier for your device.
</ParamField>

<ParamField path="hardware_name" type="string" required>
  The name of the hardware model used in the device, such as 'RTX A6000'.
</ParamField>

<ParamField path="hardware_quantity" type="integer" required>
  The number of hardware components (GPUs) in the device.
</ParamField>

<ParamField path="base_tier_name" type="string" required>
  The performance tier assigned to the device based on its network speed.
</ParamField>

***

## Performance Metrics

<ParamField path="down_percentage" type="integer" required>
  The percentage of time the device was unavailable.
</ParamField>

<ParamField path="download_speed_mbps" type="integer" required>
  The average download speed, measured in megabits per second (Mbps).
</ParamField>

<ParamField path="upload_speed_mbps" type="integer" required>
  The average upload speed, measured in megabits per second (Mbps).
</ParamField>

<ParamField path="downtime_by_date" type="object" required>
  A breakdown of downtime occurrences by date.

  <Expandable title="properties">
    <ParamField path="downtime_by_date.key" type="string" required>
      Date of downtime in `YYYY-MM-DD` format.
    </ParamField>

    <ParamField path="downtime_by_date.value" type="array" required>
      Each entry represents a day's downtime data.

      <Expandable title="properties">
        <ParamField path="downtime_by_date.value.downtime" type="number" required>
          Total downtime duration in seconds.
        </ParamField>

        <ParamField path="downtime_by_date.value.note" type="string" required>
          Human-readable note summarizing downtime (e.g., “down for 0 days and 3 hours and 23 minutes”).
        </ParamField>

        **Example**

        ```json theme={null}
        {
          "2023-09-11": {
            "downtime": 281.508,
            "note": "down for 0 days and 0 hours and 4 minutes"
          },
          "2023-09-12": {
            "downtime": 12193.385,
            "note": "down for 0 days and 3 hours and 23 minutes"
          }
        }
        ```
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

***

## Location & Branding

<ParamField path="iso2" type="string" required>
  The country ISO code (e.g., `CA` for Canada).
</ParamField>

<ParamField path="location_name" type="string" required>
  The name of the country or region where the device is located.
</ParamField>

<ParamField path="location_icon" type="string" required>
  The URL of the location icon.
</ParamField>

<ParamField path="brand_icon" type="string" required>
  The web address of the device’s associated brand icon.
</ParamField>

***

## Compliance & Status

<ParamField path="security_soc2" type="boolean" required>
  Indicates whether the device meets SOC 2 (System and Organization Controls 2) compliance standards.
</ParamField>

<ParamField path="status" type="string" required>
  The current status of the device or job running on it.
</ParamField>

***

## Job History

<ParamField path="jobs" type="array" required>
  An array of job entries representing each compute job executed on this device.

  <Expandable title="properties">
    <ParamField path="jobs.compute_minutes_hired" type="integer" required>
      Total minutes a customer hired the device.
    </ParamField>

    <ParamField path="jobs.compute_minutes_served" type="integer" required>
      Total minutes the device was active during the job.
    </ParamField>

    <ParamField path="jobs.earned" type="integer" required>
      Total \$IO earnings for this job.
    </ParamField>

    <ParamField path="jobs.slashed" type="integer" required>
      Earnings deducted (slashed) for downtime or failed performance.
    </ParamField>

    <ParamField path="jobs.total_hire_rate" type="integer" required>
      The full payment rate if the device achieved 100% uptime.
    </ParamField>

    <ParamField path="jobs.uptime_percent" type="integer" required>
      Percentage of uptime during the job.
    </ParamField>

    <ParamField path="jobs.start_time" type="datetime string" required>
      UTC timestamp when the job started.
    </ParamField>

    <ParamField path="jobs.end_time" type="datetime string" required>
      UTC timestamp when the job ended.
    </ParamField>

    <ParamField path="jobs.status" type="string" required>
      Job status (e.g., `pending`, `running`, `completed`).
    </ParamField>

    <ParamField path="jobs.for" type="string" required>
      Cluster ID associated with the job.
    </ParamField>

    **Example**

    ```json theme={null}
    {
      "jobs": [
        {
          "compute_minutes_hired": 300,
          "compute_minutes_served": 0,
          "earned": 0,
          "end_time": "2023-09-12 00:00:00",
          "for": "e242cd76-9e65-4de1-b3ec-1cb8b002b38d",
          "slashed": 0,
          "start_time": "2023-09-12 00:00:00",
          "status": "pending",
          "total_hire_rate": 10.8,
          "uptime_percent": 100
        }
      ]
    }
    ```
  </Expandable>
</ParamField>