Python SDK

The SDK exposes two clients with identical method names — Meshive (synchronous) and AsyncMeshive (asyncio). Both read the same credentials and configuration as the CLI (see Authentication).

Read-only beta

The SDK wraps read endpoints only. There are no create/update/delete methods yet.

Quick start

Sync

from meshive import Meshive

with Meshive() as client:               # reads MESHIVE_API_KEY
    me = client.me()
    print(me.email, me.user_role)

    for ws in client.list_workspaces():
        print(ws.namespace_name, ws.status)

    detail = client.get_workspace("my-workspace")
    print(detail.price_per_hour, detail.gpus)

    pods = client.list_pods("my-workspace")
    pod = client.get_pod(pods[0].pod_name, "my-workspace")
    print(pod.status, pod.raw)           # .raw holds the full payload

    usage = client.get_pod_metrics(pod.pod_name, "my-workspace")
    print(usage.cpu_usage_rate, [g.vram_usage_rate for g in usage.gpus])

    # what can I rent right now?
    for gpu in client.list_gpus(min_vram=40):
        print(gpu.gpu_model, gpu.vram, gpu.price_per_hour, gpu.available_gpus)

    credit = client.get_credit()
    print(credit.paid_balance, credit.bonus_balance)

    # host view: the machines you contribute to the network
    machines = client.list_machines()
    for m in machines:
        print(m.machine_id, m.status, m.gpu_count, m.gpu_model)
    machine = client.get_machine(machines[0].machine_id)
    print(machine.earning_hourly, machine.raw)

Async

import asyncio
from meshive import AsyncMeshive

async def main():
    async with AsyncMeshive() as client:
        me = await client.me()
        print(me.email, me.user_role)

        pods = await client.list_pods("my-workspace")
        pod = await client.get_pod(pods[0].pod_name, "my-workspace")
        print(pod.status, pod.raw)

        gpus = await client.list_gpus(min_vram=40)
        tasks = await client.list_tasks("my-workspace", status="running")

        machines = await client.list_machines()
        machine = await client.get_machine(machines[0].machine_id)
        print(machine.earning_hourly)

asyncio.run(main())

Using the client as a context manager (with / async with) ensures the underlying HTTP connection is closed. Otherwise, call client.close() (or await client.close()) yourself.

Constructing a client

Meshive(api_key=None, *, base_url=None, timeout=30.0, max_retries=2)
AsyncMeshive(api_key=None, *, base_url=None, timeout=30.0, max_retries=2)

With no arguments, credentials resolve in the usual order (explicit argument › environment variable › meshive login file). You can also pass the key explicitly:

client = Meshive(api_key="meshive_xxxxxxxx")

timeout is the per-request timeout in seconds (default 30.0). max_retries controls automatic retries of rate limits, gateway errors and dropped connections (0 disables them). If no API key can be resolved, the first request raises ConfigurationError.

Methods

Both clients expose the same methods (await them on AsyncMeshive):

Method	Returns	Description
me()	WhoAmI	The current API key’s owner.
list_api_keys()	list[ApiKey]	Your active API keys (prefixes only).
get_credit()	Credit	Credit balance and auto-recharge setting.
list_credit_history(*, start_date=None, end_date=None)	list[CreditHistoryEntry]	Top-ups and refunds (default: last 90 days).
list_workspaces()	list[Workspace]	Workspaces you can access.
get_workspace(workspace)	WorkspaceDetail	Cost and resource summary of one workspace.
list_members(workspace)	list[Member]	Members of a workspace.
list_pods(workspace)	list[Pod]	Pods in a workspace (by ID).
get_pod(pod_name, workspace)	Pod	A single pod.
wait_for_pod(pod_name, workspace, *, until="running", timeout=600, interval=5)	Pod	Poll until the pod reaches a status.
get_pod_metrics(pod_name, workspace)	PodMetrics	Live CPU/RAM/GPU/disk usage of a pod.
list_storages(workspace)	list[Storage]	Storages (volumes) in a workspace.
get_storage(storage_name, workspace)	Storage	A single storage.
list_gpus(*, rental_type="demand", min_vram=None)	list[GpuAvailability]	GPU tiers you can rent right now, with prices.
list_templates(workspace=None, *, app_type=None)	list[Template]	Official templates, plus a workspace’s custom ones when workspace is given.
get_template(template_id, workspace=None)	Template	A single template (custom ones need their workspace).
list_servings(workspace)	list[Serving]	Serverless serving deployments in a workspace.
get_serving(serving_id)	Serving	A single serving deployment.
list_tasks(workspace, *, status=None, limit=50, offset=0)	list[Task]	Serverless tasks, newest first. status is a string or list of statuses.
get_task(task_id)	Task	A single task.
list_assets(workspace, *, asset_type=None, status=None, page=1, page_size=20)	AssetPage	One page of a workspace’s assets. Iterate it, or read .items, .total, .pages.
get_asset(asset_id)	Asset	A single asset with its version stack.
get_asset_storage(workspace)	AssetStorage	Managed asset storage usage, cost, and credit status.
list_machines()	list[Machine]	Machines you host.
get_machine(machine_id)	Machine	A single machine.
get_machine_metrics(machine_id)	MachineMetrics	Live metrics of a machine.
get_earnings(*, start_date=None, end_date=None)	Earnings	Host earnings summary and daily history.

Note

Note the argument order of get_pod(pod_name, workspace), get_storage(storage_name, workspace) and get_pod_metrics(pod_name, workspace) — the resource ID comes first, then the workspace ID. Dates accept datetime.date, datetime.datetime, or a "YYYY-MM-DD" string. Invalid arguments (a malformed date, limit outside 1–200, an empty ID) raise ValueError before any request is sent.

Models

Responses are parsed into lightweight dataclasses. Frequently used scalar fields are typed; deeply nested structures aren’t enumerated — the full original payload is preserved on .raw, so the SDK keeps working even when the backend adds fields.

WhoAmI

Field	Type	Notes
email	str
username	str | None
user_role	str
raw	dict	Full payload.

Workspace

Field	Type	Notes
namespace_name	str	ID — pass to list_pods / get_pod.
workspace_name	str	Display label.
description	str
member_count	int
status	str
price_per_hour	str
resources	WorkspaceResources	.pod, .storage, .serverless counts. Includes stopped pods and paused deployments.
created_at / updated_at	datetime | None
raw	dict	Full payload.

To count only what a workspace is actually running, read ws.raw["activeResources"] — same three keys, but pods you stopped and deployments you paused are left out. A typed field will follow in a later SDK release.

Pod

Field	Type	Notes
pod_name	str	ID — pass to get_pod.
namespace_name	str	Owning workspace ID.
user_alias	str	Display label.
status	str
rental_type	str	spot / demand.
price_per_hour	str
is_maintenance	bool
created_at	datetime | None
raw	dict	Full payload — machine, template, request, linked storages, …

Machine

Field	Type	Notes
machine_id	str	ID — pass to get_machine.
name	str	Display label.
machine_type	str	gpu / cpu / storage.
status	str
gpu_model	str	Empty for cpu/storage machines.
gpu_count	int
earning_hourly	float
uptime_rate	float	0.0–1.0.
host_tier	str
raw	dict	Full payload — specs, full state, pod uses, …

WorkspaceDetail

Field	Type	Notes
namespace_name / workspace_name	str	ID / display label.
price_per_hour	str	What the workspace is being billed right now.
weekly_avg_daily_cost	str	Average daily cost over the last 7 days.
gpus / vcpus	int	Totals across the workspace’s pods.
ram / total_storage	int / float	In MiB (divide by 1024 for GB).
resources	list[ResourceCondition]	One per type (pod, storage, serverless) with .active, .paused, .disabled.
costs	list[DailyCost]	Recent daily costs (.date, .pod, .storage, .serverless, .task, .asset, .total).
raw	dict	Full payload — maintenance schedule, messages from hosts, …

Member

user (email), role (admin / billing / viewer), joined_at, raw.

Storage

Field	Type	Notes
pv_name	str	ID — pass to get_storage.
namespace_name / user_alias	str	Owning workspace / display label.
storage_type	str	nfs, hostPath, …
status	str
total_size / available_size	float	In MiB.
usage_rate	float	0.0–1.0.
price_per_hour	str
linked_pods	list[str]	Names of the pods it is mounted in.
is_maintenance / encrypted	bool
created_at	datetime | None
raw	dict	Full payload — host machine, warning thresholds, …

PodMetrics and MachineMetrics

Both expose cpu_cores, cpu_usage_rate, ram_size (MiB), ram_usage_rate, and gpus — a list of GpuUsage with gpu_number, core_usage_rate, vram_usage_rate, vram_size (MiB) and temp. Rates are 0.0–1.0; a pod rate is None when the measurement is unavailable. PodMetrics adds ephemeral_storage_request / ephemeral_storage_usage (MiB); MachineMetrics adds cpu_allocated, ram_allocated, root_volume_size / root_volume_usage_rate, pv_volume_size / pv_volume_usage_rate, and network_receive / network_transmit (bytes per second).

GpuAvailability

Field	Type	Notes
gpu_model	str
vram	int	GB. One entry per (model, VRAM) tier.
rental_type	str	demand / spot — the type the price is for.
price_per_hour	str	Per GPU.
vcpu_recommended / ram_recommended	int	Suggested pairing per GPU.
available_gpus	int	Total across machines.
max_gpus_per_pod	int	The most one pod can get on a single machine.
machine_count	int
raw	dict	Full payload — per-machine combinations, CPU/RAM prices, …

ApiKey, Credit, CreditHistoryEntry

• ApiKey: key_id, name, prefix (meshive_a1b2c3d4 — the secret is never returned), scopes, status, created_at, last_used_at, expires_at.
• Credit: balance, paid_balance (GPU pods and workspaces), bonus_balance (serverless inference only), auto_recharge, auto_recharge_threshold, auto_recharge_amount, has_default_payment_method.
• CreditHistoryEntry: entry_id, amount (negative for refunds), is_paid, payment_method, created_at. Stripe receipt and invoice links are not exposed to the SDK.

Template

template_id (ID), name, description, is_official, deploy_type, app_type, app_sub_type, image, hardware_type, cuda_version, framework, framework_version, raw (environment variables, endpoints, volume mounts, semantic paths).

Serving

serving_id (ID), namespace_name, model_name, api_model_id, framework, status, paused, min_replicas / max_replicas / current_replicas / healthy_replicas, endpoint_url, price_per_hour, billing_active, raw (replicas, live metrics, scaling state).

Task

task_id (ID, task_…), name, namespace_name, status, pod_name, image, gpu_model, gpu_count, cpu_cores, ram_gb, price_per_hour, cost_so_far, total_cost, created_at, container_running_at, finished_at, failure_reason, exit_code, raw. For get_task the payload also carries the script, requirements, environment (secret values masked) and the compute/disk cost breakdown.

Asset, AssetVersion, AssetPage, AssetStorage

Field	Type	Notes
Asset.asset_id	str	ID (asset_…) — pass to get_asset.
Asset.name / asset_type / status / status_reason	str	Type is one of dataset, model, adapter, checkpoint, output, config, file.
Asset.storage_provider	str	meshive_r2 (managed), user_s3, or external.
Asset.version_count / size_bytes / file_count	int	Ready versions; size and files of the latest ready version.
Asset.in_use	bool	Whether a pod or task currently uses it (raw["activeUsageContexts"] says which).
Asset.latest_version / versions	AssetVersion / list[AssetVersion]	versions is filled by get_asset only (newest first).
AssetVersion		version_number, status (uploading / ready / failed), total_size_bytes, file_count, ingest_source, storage_provider, created_at, deleted, import_failure_reason; file entries in raw["files"].
AssetPage		items, total, page, page_size, pages; iterable.
AssetStorage		managed_bytes, price_per_gb_month, estimated_monthly_cost, credit_state (normal / grace / blocked), credit_blocked, blocks_at, purge_deadline_at, paid_balance_available.

Earnings

current_hourly, daily, accumulated_until_payout, and history — a list of DailyEarning (date, cpu, gpu, storage, total), newest first.

Reach for .raw

The typed fields cover the common cases. For anything else — a pod’s machine assignment, a machine’s detailed specs, a serving’s replicas — read it from .raw, which is the exact JSON the API returned.

Errors

All SDK errors subclass MeshiveError:

Exception	When
ConfigurationError	No API key could be resolved (raised before any request).
AuthenticationError	401 — missing/invalid/expired key, or an inactive account.
PermissionDeniedError	403 — the key lacks the required scope.
NotFoundError	404 — the resource doesn’t exist.
RateLimitError	429 — rate limit exceeded. Exposes .retry_after (seconds, may be None).
MeshiveAPIError	Any other 4xx/5xx.

MeshiveAPIError (and its subclasses) carry .status_code, .title, .message, and .raw (the parsed response body).

from meshive import Meshive, MeshiveError, RateLimitError, NotFoundError

try:
    with Meshive() as client:
        pod = client.get_pod("does-not-exist", "my-workspace")
except NotFoundError as err:
    print("no such pod:", err.message)
except RateLimitError as err:
    print("slow down; retry after", err.retry_after, "s")
except MeshiveError as err:
    print("request failed:", err)

Importable names

from meshive import (
    Meshive, AsyncMeshive,                                  # clients
    WhoAmI, ApiKey, Credit, CreditHistoryEntry,             # account
    Workspace, WorkspaceResources, WorkspaceDetail,         # workspaces
    ResourceCondition, DailyCost, Member,
    Pod, PodMetrics, Storage, GpuUsage,                     # pods / storage
    Asset, AssetVersion, AssetPage, AssetStorage,           # assets
    GpuAvailability, Template,                              # catalog
    Serving, Task,                                          # serverless
    Machine, MachineMetrics, Earnings, DailyEarning,        # host
    MeshiveError, ConfigurationError, MeshiveAPIError,      # errors
    AuthenticationError, PermissionDeniedError,
    NotFoundError, RateLimitError, WaitTimeoutError,
    __version__,
)