--- title: "Get the billing history for a provider" method: GET path: "/billing/billing-history/{miner_coldkey}" tags: ["Public APIs For Providers"] --- # Get the billing history for a provider `GET /billing/billing-history/{miner_coldkey}` ## Request - Base URL: `https://lium.io/api` - URL: `https://lium.io/api/billing/billing-history/{miner_coldkey}` - Auth: none declared ## Path parameters - `miner_coldkey` string, required ## Response `200` Get the billing history for a provider - BillingHistoryForMinerResponse[] - `billing_day` string, required - `amount` number, required - `miner_amount` number, required - `validator_hotkey` string, required - `is_declined_for_miner_payment` boolean - `declined_reason` string, nullable - `executor_id_in_subnet` string, uuid, nullable - `executor_price_per_gpu` number, nullable - `executor_gpu_count` integer, nullable - `executor_specs` MachineSpecs - `gpu` GpuSpec, required - `count` integer, required - `driver` string, nullable - `cuda_driver` integer, nullable - `details` GpuDetail[], required - `name` string, required - `cuda` string, required - `power_limit` integer, required - `power_default_limit` integer, nullable - `power_max_limit` integer, nullable - `power_min_limit` integer, nullable - `graphics_speed` integer, required - `memory_speed` integer, required - `pcie` integer, nullable - `pcie_speed` integer, nullable - `capacity` integer, required - `gpu_utilization` number, nullable - `memory_utilization` number, nullable - `memory_used_mb` number, nullable - `uuid` string, required - `cpu` CpuSpec, required - `count` integer, required - `model` string, required - `utilization` number, nullable - `ram` MemorySpec, required - `total` number, required - `used` number, required - `free` number, required - `available` number, nullable - `utilization` number, nullable - `hard_disk` HardDiskSpec - `total` integer, required - `used` integer, required - `free` integer, required - `utilization` number, nullable - `images` integer, nullable - `containers` integer, nullable - `volumes` integer, nullable - `disk_type` 'nvme' | 'ssd' | 'hdd' | 'unknown', nullable - `os` string, nullable - `kernel` string, nullable - `kernel_scrape_error` string, nullable - `network` NetworkSpec - `upload_speed` number, nullable - `download_speed` number, nullable - `verifyx_download_speed` number, nullable - `verifyx_upload_speed` number, nullable - `ema_download_speed` number, nullable - `ema_upload_speed` number, nullable - `ema_verifyx_download_speed` number, nullable - `ema_verifyx_upload_speed` number, nullable - `md5_checksums` Checksums - `nvidia_smi` string, nullable - `libnvidia_ml` string, nullable - `docker` string, nullable - `docker` DockerSpec - `version` string, nullable - `container_id` string, nullable - `containers` object[], nullable - `host_cpu_percent` number, nullable - `gpu_processes` object[], nullable - `available_port_maps` array[], nullable - unknown[] - unknown - `available_port_count` integer, nullable - `sysbox_runtime` boolean, nullable - `sysbox_version` string, nullable - `storage_limit_supported` boolean, nullable - `ncu_profiling_access` string, nullable - `ncu_profiling_scrape_error` string, nullable - `container_cap_eff` string, nullable - `nvidiactl_owner_uid` integer, nullable - `power_cap_probe_error` string, nullable - `boot_id` string, nullable - `port_range` string, nullable - `port_mappings` string, nullable - `verified_ports` integer[], nullable - `tdx_attestation_passed` boolean, nullable - `tdx_host_supported` boolean, nullable - `is_spot` boolean, nullable - `gpu_metrics` GpuMetrics: FP32 throughput metrics from libdmcompverify.so getMetrics() (device-0 representative). All fields are optional: the .so may emit a subset, and the whole object is absent when TFLOPS benchmarking is disabled or fails (fail-safe). CONTRACT OBLIGATION: this model mirrors getMetrics() output. Because MachineSpecs has `extra` unset (Pydantic defaults to ignore -> undeclared keys are stripped on validation), any NEW field that libdmcompverify.so's getMetrics() starts emitting MUST be added here too, or it is silently dropped on coercion. Adding the field here is the documented way to surface it; failing to do so is a silent-strip data-loss bug, not a crash. - `device` string, nullable - `cc` string, nullable - `sm_count` integer, nullable - `clock_mhz` integer, nullable - `vram_gb` number, nullable - `n` integer, nullable - `fp32_tflops` number, nullable - `fp32_median_tflops` number, nullable - `fp32_cov_pct` number, nullable - `infiniband_ports` InfinibandPortSpec[], nullable - `device` string, nullable - `port` string, nullable - `node_guid` string, nullable - `sys_image_guid` string, nullable - `link_layer` string, nullable - `state` string, nullable - `phys_state` string, nullable - `rate` string, nullable - `lid` string, nullable - `sm_lid` string, nullable - `pkey` string, nullable - `gids` string[], nullable - `infiniband_scrape_error` string, nullable - `roce_link_measurements` RoceLinkMeasurementSpec[], nullable - `peer_executor_uuid` string, required - `peer_address` string, required - `gigabits_per_second` number, nullable - `measured_at` string, required - `provider_side_load` ProviderSideLoadSpec: DAH-2734: what the machine's OWNER consumes outside Lium's containers. The validator computes it and sends it with the specs, so the fleet cut is a plain JSON read. Each part is None when the scrape could not measure it that cycle - never a guess. - `cpu_cores` number, nullable - `disk_kb` integer, nullable - `kernel_gpu_uuids` string[], nullable - `kernel_gpu_uuids_last_seen` string[], nullable - `disk_health` DiskHealthSpec: DAH-2929: the validator's disk probe (lium-io DAH-2928, lium-io#1278), one cycle's readings. lium-io#1278 (15 Sep, value audit) sends four keys: ``docker_root_dir``, ``read_only_mounts``, ``write_probe`` and ``write_probe_error``. Each is what the scrape measured that cycle; None or empty where it could not. The dmesg, sysfs, NVMe and SMART readers were cut from the probe before it shipped and are not declared here; a follow-up in lium-io that re-adds a reader declares its key here in the same change. CONTRACT OBLIGATION (same as GpuMetrics): MachineSpecs validates with Pydantic's default ``extra="ignore"``, so a probe key the validator starts emitting that is not declared here is stripped on the upsert, not stored. Declare it here to keep it. Only PUBLIC_DISK_HEALTH_FIELDS leave the API on the anonymous routes (``ExecutorForPodResponse`` and ``BillingHistoryForMinerResponse`` serialize specs through ``public_specs_projection``; ``ExecutorForProviderResponse`` declares the same two fields in ``PublicDiskHealth``, DAH-3462): the free-text readings (docker root path, exception text) stay in the stored specs for operators. The one route that serves the full row is the machine request owner's ``GET /machine-requests/{id}/executors`` (DAH-2554: ip, ssh port, coldkey by design). - `docker_root_dir` string, nullable - `read_only_mounts` string[], nullable - `write_probe` string, nullable - `write_probe_error` string, nullable - `disk_health_scrape_error` string, nullable - `interconnect` InterconnectSpec: How the GPUs of one host are wired to each other, from the validator's `nvidia-smi topo` run. Scraped by lium-io DAH-2922, declared and exposed here (DAH-2923). `nvlink` is True only when EVERY GPU pair is joined by NVLink (an HGX board); a box with NVLink bridges on some pairs reports False with `nvlink_pairs` < `gpu_pairs`. `p2p` is True only when every pair of `nvidia-smi topo -p2p r` reads OK — False is the host where NCCL cannot start without NCCL_P2P_DISABLE=1. Both are None on a single-GPU host (nothing to judge) and when the table that answers them could not be read (`interconnect_scrape_error` on MachineSpecs says why). `pcie_class` is nvidia-smi's worst class among the non-NVLink pairs (SYS > NODE > PHB > PXB > PIX). `matrix` is the GPU x GPU cell table, kept so a client can print the topology. - `gpu_count` integer, nullable - `gpu_pairs` integer, nullable - `nvlink` boolean, nullable - `nvlink_links` integer, nullable - `nvlink_pairs` integer, nullable - `nvlink_active_links` integer, nullable - `pcie_class` string, nullable - `p2p` boolean, nullable - `p2p_pairs` integer, nullable - `p2p_ok_pairs` integer, nullable - `matrix` array[], nullable - string[] - `interconnect_scrape_error` string, nullable - `gpu_activity` GpuActivitySpec[], nullable - `index` integer, required - `uuid` string, nullable - `util_pct` number, nullable - `vram_used_mb` number, nullable - `vram_total_mb` number, nullable - `no_pod` boolean, required - `gpu_power_cap_capable` boolean, nullable, required - `user_id` string, uuid, nullable ## Other responses - `422`: Validation Error ## Changes - **2026-10-15** `798ab1f71f56`: 1 info - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/network/anyOf[subschema #1: NetworkSpec]/verifyx_upload_speed` to the response with the `200` status - **2026-10-07** `6becefc4fb36`: 1 info - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/sysbox_version` to the response with the `200` status - **2026-09-22** `4dfc08fc01cc`: 1 info - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/gpu_activity` to the response with the `200` status - **2026-09-21** `37963d1ef9fe`: 1 info - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/hard_disk/anyOf[subschema #1: HardDiskSpec]/disk_type` to the response with the `200` status - **2026-09-17** `f380a826774d`: 8 info - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/disk_health` to the response with the `200` status - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/disk_health_scrape_error` to the response with the `200` status - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/gpu/details/items/power_min_limit` to the response with the `200` status - added the optional property `items/executor_specs/anyOf[subschema #1: MachineSpecs]/interconnect` to the response with the `200` status - …4 more [Operation history](https://skmtc.dev/lium/apis/lium-backend-api/changes/billing/billing-history/:miner_coldkey/get.md) --- [API](https://skmtc.dev/lium/apis/lium-backend-api.md) · [All operations](https://skmtc.dev/lium/apis/lium-backend-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lium/apis/lium-backend-api/revisions/a682d3ef1e07?raw)