ComputeNexa
Contents

Python SDK reference

computenexa 0.2.0. Every method, with its request syntax, parameters, return value and exceptions. New here? Start with the overview and quickstart. Source on GitHub.

Client

computenexa.Client(api_key=None, *, base_url=None, timeout=30.0, max_retries=3, http_client=None)

A client for the ComputeNexa API. Reads the key from CNX_API_KEY (and the address from CNX_API_URL) when not given. Use it as a context manager to close its connections.

Request Syntax

from computenexa import Client cnx = Client( api_key='cnxk_...', base_url='https://api.computenexa.com/v1', timeout=30.0, max_retries=3, )

Parameters

  • api_key (str) – An API key from the dashboard (API keys). Default: the CNX_API_KEY environment variable.
  • base_url (str) – Default: CNX_API_URL, else https://api.computenexa.com/v1.
  • timeout (float) – Seconds per request. Default 30.
  • max_retries (int) – Retries of reads on 429, 5xx and network errors, and of any request on 429. Default 3.
  • http_client (httpx.Client) – Your own HTTP client (proxies, custom transport).

Return type

Client

Returns

A client.

Exceptions

  • ComputeNexaError (no key, or not a cnxk_ key)

account

Client.account()

Who this key acts as, their team, the team's balance and its GPU limit.

See also: getAccount in the HTTP API reference.

Request Syntax

account = cnx.account()

Parameters

None.

Return type

Account

Response Syntax

Account( id='string', email='string', balance_cents=123, balance=123.0, max_concurrent_gpus=123, organization=Organization(id='string', name='string', role='owner'|'admin'|'member', members=123), )

Response Structure

Account: Who the API key acts as, and their team.

  • id (str)
  • email (str)
  • balance_cents (int) – The team's balance, in US cents.
  • balance (float) – The same, in US dollars.
  • max_concurrent_gpus (int) – How many GPUs the team can run at once.
  • organization (Organization)
    • id (str)
    • name (str)
    • role (str) – Your role: 'owner' | 'admin' | 'member'.
    • members (int)
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Example

me = cnx.account() print(me.email, me.organization.name, me.organization.role, me.balance)

balance_cents

Client.balance_cents()

The team's credit balance, in US cents.

See also: getBalance in the HTTP API reference.

Request Syntax

cents = cnx.balance_cents()

Parameters

None.

Return type

int

Returns

The balance in US cents (9677 = $96.77).

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

ledger

Client.ledger(limit=50)

Charges, refunds and top-ups, newest first. Owners and admins get the team's; members the lines they caused.

See also: listLedgerEntries in the HTTP API reference.

Request Syntax

entries = cnx.ledger( limit=50, )

Parameters

  • limit (int) – 1 to 10,000. Default 50.

Return type

list[LedgerEntry]

Response Syntax

[ LedgerEntry( created_at=datetime(2026, 10, 28, 9, 0), kind='string', amount_cents=123, description='string', instance='string', ), ]

Response Structure

A list of LedgerEntry objects: A charge, refund or top-up.

  • created_at (datetime | None)
  • kind (str) – 'topup' | 'charge' | 'refund' | 'adjustment'.
  • amount_cents (int) – + credit, − debit.
  • description (str)
  • instance (str | None) – The machine it's for, if any.
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

catalog

Client.catalog(region=None)

GPUs with live prices and stock, the apps each runs, and the models offered for each app.

See also: getCatalog in the HTTP API reference.

Request Syntax

catalog = cnx.catalog( region='us'|'ca', )

Parameters

  • region (str) – 'us' or 'ca': only GPUs offered in that country, at that country's price. Default: anywhere.

Return type

Catalog

Response Syntax

Catalog( region='string', gpus=[...], apps={...}, )

Response Structure

Catalog: GPUs with live prices and stock, and the apps they run.

  • region (str) – 'any', 'us' or 'ca'.
  • gpus (list[Gpu])
    • slug (str) – What you launch with, e.g. 'rtx-4090'.
    • name (str) – e.g. 'NVIDIA RTX 4090'.
    • vram_gb (int)
    • available (bool) – For sale right now.
    • price_per_hour_cents (int | None) – None when not for sale right now.
    • billing_unit (str) – 'minute', or 'hour' (billed per started hour).
    • apps (list[str]) – The apps it runs.
    • regions (list[str])
  • apps (dict[str, App])
    • name (str) – The value for app=.
    • display_name (str) – As on the launch page.
    • summary (str)
    • needs_ssh_key (bool)
    • models (list[dict]) – Models offered: name, label, size_gb, min_vram_gb, note, licence, gated.
    • model_required (bool)
    • recommended (list[tuple[int, str]]) – (min GPU memory in GB, model); first match wins.
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Example

catalog = cnx.catalog() for gpu in catalog.available(app='chat'): print(gpu.slug, gpu.vram_gb, gpu.price_per_hour_cents / 100)

image_contents

Client.image_contents(app)

What's installed in an app's images: Ubuntu, CUDA, Python, headline libraries, tools and every package with its version.

See also: getImageFamily in the HTTP API reference.

Request Syntax

contents = cnx.image_contents( app='basic'|'datascience'|'chat'|'imagegen'|'modelapi'|'voice', )

Parameters

  • app (str) [REQUIRED] – The app (image family).

Return type

dict

Returns

{'family', 'display_name', 'summary', 'images': [{'slug', 'display_name', 'cuda_version', 'manifest': {...}}]}

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

launch

Client.launch(gpu, *, app=None, image=None, minutes=None, hours=None, gpu_count=1, region='any', label=None, model=None, project=None)

Launch a GPU. It's charged now for the booked time; unused time is refunded when it stops early, all of it if it can't start. Returns at once: use wait_until_running(), or Client.gpu() for a with-block.

See also: launchInstance in the HTTP API reference.

Request Syntax

machine = cnx.launch( 'rtx-4090', app='basic'|'datascience'|'chat'|'imagegen'|'modelapi'|'voice', hours=123.0, # or minutes=123 gpu_count=1, region='any'|'us'|'ca', label='string', model='string', project=Project|'string', )

Parameters

  • gpu (str) [REQUIRED] – A GPU's slug from catalog(), e.g. 'rtx-4090'.
  • app (str) – What's on the machine (the launch page's "What do you want to do?"). Give app or image.
  • image (str) – An exact image slug instead of app.
  • minutes (int) – How long to book. Give minutes or hours (up to 7 days).
  • hours (float) – How long to book, in hours.
  • gpu_count (int) – GPUs in one machine. Default 1.
  • region (str) – 'any' (default), 'us' or 'ca'.
  • label (str) – A name to tell machines apart.
  • model (str) – For apps that take one: a model name from catalog().apps[app].models. Default: the recommended one.
  • project (Project | str) – A project (or its id) to restore into ~/work and save back.

Return type

Instance

Response Syntax

Instance( id='string', state='string', gpu='string', gpu_count=123, app='string', label='string', price_per_hour_cents=123, ssh_command='string', expires_at=datetime(2026, 10, 28, 9, 0), time_left_seconds=123, charged_cents=123, refunded_cents=123, cost_so_far_cents=123, end_reason='string', startup_progress='string', api_base_url='string', is_running=True|False, is_active=True|False, )

Response Structure

Instance: A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Exceptions

  • InsufficientCreditsError
  • NoCapacityError
  • GpuLimitReachedError
  • ProjectInUseError
  • InvalidRequestError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError
  • ValueError (app/image or minutes/hours missing or both given)

Example

machine = cnx.launch('l40s', app='datascience', hours=4, label='nightly') machine.wait_until_running() print(machine.ssh_command)

gpu

Client.gpu(gpu, *, wait=True, timeout=900, **launch)

A context manager: launches a GPU, waits until it's running, and stops it when the with-block ends, even if your code raises. Unused time is refunded.

Request Syntax

with cnx.gpu( 'rtx-4090', app='datascience', hours=2, wait=True, timeout=900, ) as machine: ...

Parameters

  • gpu (str) [REQUIRED] – As in launch().
  • wait (bool) – Wait until it's running before entering the block. Default True.
  • timeout (float) – Seconds to wait. Default 900.
  • **launch () – Every other launch() argument (app, hours, project, model…).

Return type

Instance (in the with-block)

Response Syntax

Instance( id='string', state='string', gpu='string', gpu_count=123, app='string', label='string', price_per_hour_cents=123, ssh_command='string', expires_at=datetime(2026, 10, 28, 9, 0), time_left_seconds=123, charged_cents=123, refunded_cents=123, cost_so_far_cents=123, end_reason='string', startup_progress='string', api_base_url='string', is_running=True|False, is_active=True|False, )

Response Structure

Instance: A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Exceptions

  • LaunchFailedError
  • WaitTimeoutError
  • the launch() exceptions

Example

with cnx.gpu('rtx-4090', app='datascience', hours=2) as machine: print(machine.ssh_command) ... # your work # stopped here

get_instance

Client.get_instance(instance_id)

One machine, with its current state.

See also: getInstance in the HTTP API reference.

Request Syntax

machine = cnx.get_instance( 'cnx-7f3a9c', )

Parameters

  • instance_id (str) [REQUIRED] – e.g. 'cnx-7f3a9c'.

Return type

Instance

Response Syntax

Instance( id='string', state='string', gpu='string', gpu_count=123, app='string', label='string', price_per_hour_cents=123, ssh_command='string', expires_at=datetime(2026, 10, 28, 9, 0), time_left_seconds=123, charged_cents=123, refunded_cents=123, cost_so_far_cents=123, end_reason='string', startup_progress='string', api_base_url='string', is_running=True|False, is_active=True|False, )

Response Structure

Instance: A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

list_instances

Client.list_instances(*, active=None, everyone=False, limit=50)

Your machines, newest first.

See also: listInstances in the HTTP API reference.

Request Syntax

machines = cnx.list_instances( active=True|False, everyone=True|False, limit=50, )

Parameters

  • active (bool) – True: only starting and running ones; False: only ended ones. Default: all.
  • everyone (bool) – The whole team's machines (owners and admins). Default False.
  • limit (int) – 1 to 200. Default 50.

Return type

list[Instance]

Response Syntax

[ Instance( id='string', state='string', gpu='string', gpu_count=123, app='string', label='string', price_per_hour_cents=123, ssh_command='string', expires_at=datetime(2026, 10, 28, 9, 0), time_left_seconds=123, charged_cents=123, refunded_cents=123, cost_so_far_cents=123, end_reason='string', startup_progress='string', api_base_url='string', is_running=True|False, is_active=True|False, ), ]

Response Structure

A list of Instance objects: A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

extend_instance

Client.extend_instance(instance_id, *, minutes=None, hours=None)

Add time to a running machine at the price it launched with. Same as Instance.extend().

See also: extendInstance in the HTTP API reference.

Request Syntax

machine = cnx.extend_instance( 'cnx-7f3a9c', hours=1.0, # or minutes=60 )

Parameters

  • instance_id (str) [REQUIRED]
  • minutes (int)
  • hours (float)

Return type

Instance

Response Syntax

Instance( id='string', state='string', gpu='string', gpu_count=123, app='string', label='string', price_per_hour_cents=123, ssh_command='string', expires_at=datetime(2026, 10, 28, 9, 0), time_left_seconds=123, charged_cents=123, refunded_cents=123, cost_so_far_cents=123, end_reason='string', startup_progress='string', api_base_url='string', is_running=True|False, is_active=True|False, )

Response Structure

Instance: A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Exceptions

  • InsufficientCreditsError
  • ConflictError (not running)
  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

stop_instance

Client.stop_instance(instance_id)

End a machine now: stop it if running (unused time refunded), cancel it if still starting (refunded in full). An ended machine is returned as it is. Same as Instance.stop().

See also: stopInstance in the HTTP API reference.

Request Syntax

machine = cnx.stop_instance( 'cnx-7f3a9c', )

Parameters

  • instance_id (str) [REQUIRED]

Return type

Instance

Response Syntax

Instance( id='string', state='string', gpu='string', gpu_count=123, app='string', label='string', price_per_hour_cents=123, ssh_command='string', expires_at=datetime(2026, 10, 28, 9, 0), time_left_seconds=123, charged_cents=123, refunded_cents=123, cost_so_far_cents=123, end_reason='string', startup_progress='string', api_base_url='string', is_running=True|False, is_active=True|False, )

Response Structure

Instance: A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

list_projects

Client.list_projects()

Your projects.

See also: listProjects in the HTTP API reference.

Request Syntax

projects = cnx.list_projects()

Parameters

None.

Return type

list[Project]

Response Syntax

[ Project( id='string', name='string', bytes_used=123, files=123, created_at=datetime(2026, 10, 28, 9, 0), last_used_at=datetime(2026, 10, 28, 9, 0), in_use_by='string', ), ]

Response Structure

A list of Project objects: Saved storage, restored into ~/work on GPUs launched with it and saved back automatically.

  • id (str) – Pass it (or the Project) as project= when launching.
  • name (str)
  • bytes_used (int) – Size of its files.
  • files (int) – Number of files.
  • created_at (datetime | None)
  • last_used_at (datetime | None)
  • in_use_by (str | None) – The machine using it right now, if any.
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

create_project

Client.create_project(name)

An empty project. Launch with project= to restore it into ~/work and save it back automatically.

See also: createProject in the HTTP API reference.

Request Syntax

project = cnx.create_project( 'string', )

Parameters

  • name (str) [REQUIRED] – Unique among your projects.

Return type

Project

Response Syntax

Project( id='string', name='string', bytes_used=123, files=123, created_at=datetime(2026, 10, 28, 9, 0), last_used_at=datetime(2026, 10, 28, 9, 0), in_use_by='string', )

Response Structure

Project: Saved storage, restored into ~/work on GPUs launched with it and saved back automatically.

  • id (str) – Pass it (or the Project) as project= when launching.
  • name (str)
  • bytes_used (int) – Size of its files.
  • files (int) – Number of files.
  • created_at (datetime | None)
  • last_used_at (datetime | None)
  • in_use_by (str | None) – The machine using it right now, if any.
  • raw (dict)

Exceptions

  • ConflictError (duplicate name)
  • InvalidRequestError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

get_or_create_project

Client.get_or_create_project(name)

Your project with this name (any letter case), created if there's none.

Request Syntax

project = cnx.get_or_create_project( 'string', )

Parameters

  • name (str) [REQUIRED]

Return type

Project

Response Syntax

Project( id='string', name='string', bytes_used=123, files=123, created_at=datetime(2026, 10, 28, 9, 0), last_used_at=datetime(2026, 10, 28, 9, 0), in_use_by='string', )

Response Structure

Project: Saved storage, restored into ~/work on GPUs launched with it and saved back automatically.

  • id (str) – Pass it (or the Project) as project= when launching.
  • name (str)
  • bytes_used (int) – Size of its files.
  • files (int) – Number of files.
  • created_at (datetime | None)
  • last_used_at (datetime | None)
  • in_use_by (str | None) – The machine using it right now, if any.
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

delete_project

Client.delete_project(project)

Delete a project and all its files. Refused while a GPU is using it.

See also: deleteProject in the HTTP API reference.

Request Syntax

cnx.delete_project( Project|'string', )

Parameters

  • project (Project | str) [REQUIRED]

Return type

None

Exceptions

  • ProjectInUseError
  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

list_ssh_keys

Client.list_ssh_keys()

The public SSH keys that can log in to your machines.

See also: listSshKeys in the HTTP API reference.

Request Syntax

keys = cnx.list_ssh_keys()

Parameters

None.

Return type

list[SshKey]

Response Syntax

[ SshKey( id='string', name='string', fingerprint='string', ), ]

Response Structure

A list of SshKey objects: A public SSH key that can log in to your machines.

  • id (str)
  • name (str)
  • fingerprint (str)
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

add_ssh_key

Client.add_ssh_key(name, public_key)

Add a public key, e.g. the contents of ~/.ssh/id_ed25519.pub. New machines accept it; running ones within a minute. Never a private key.

See also: addSshKey in the HTTP API reference.

Request Syntax

key = cnx.add_ssh_key( 'string', 'ssh-ed25519 AAAA... you@laptop', )

Parameters

  • name (str) [REQUIRED]
  • public_key (str) [REQUIRED]

Return type

SshKey

Response Syntax

SshKey( id='string', name='string', fingerprint='string', )

Response Structure

SshKey: A public SSH key that can log in to your machines.

  • id (str)
  • name (str)
  • fingerprint (str)
  • raw (dict)

Exceptions

  • InvalidRequestError (not a valid public key)
  • ConflictError (already added)
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

delete_ssh_key

Client.delete_ssh_key(key)

Remove an SSH key.

See also: deleteSshKey in the HTTP API reference.

Request Syntax

cnx.delete_ssh_key( SshKey|'string', )

Parameters

  • key (SshKey | str) [REQUIRED]

Return type

None

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

project_models

Client.project_models(project, app)

Models already saved in a project for an app: a launch with that model and project skips the download.

See also: listProjectModels in the HTTP API reference.

Request Syntax

models = cnx.project_models( Project|'string', app='chat'|'imagegen'|'modelapi'|'voice', )

Parameters

  • project (Project | str) [REQUIRED]
  • app (str) [REQUIRED]

Return type

list[str]

Returns

Model names.

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

model_api

Client.model_api()

Your team's stable Model API address. Its key is shown in the dashboard to owners and admins; a machine's own key: Instance.api_key().

See also: getModelApiAddress in the HTTP API reference.

Request Syntax

address = cnx.model_api()

Parameters

None.

Return type

ModelApiAddress

Response Syntax

ModelApiAddress( handle='string', base_url='string', instance='string', )

Response Structure

ModelApiAddress: Your team's stable Model API address: the same on every launch, pointing at the newest running Model API machine.

  • handle (str)
  • base_url (str) – https://<handle>-api.computenexa-apps.com/v1
  • instance (str | None) – The machine it points at now.
  • raw (dict)

Exceptions

  • NotFoundError (the Model API isn't available)
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

usage

Client.usage(days=30)

Your GPU use and spending over the last days, with breakdowns by GPU, app, day and project.

See also: getUsage in the HTTP API reference.

Request Syntax

usage = cnx.usage( days=30, )

Parameters

  • days (int) – 1 to 365. Default 30.

Return type

Usage

Response Syntax

Usage( days=123, balance_cents=123, spend_cents=123, topups_cents=123, sessions=123, gpu_hours=123.0, by_gpu=[...], by_image=[...], daily=[...], projects=[...], )

Response Structure

Usage: Your GPU use and spending over a period.

  • days (int)
  • balance_cents (int)
  • spend_cents (int)
  • topups_cents (int)
  • sessions (int)
  • gpu_hours (float)
  • by_gpu (list[dict])
  • by_image (list[dict])
  • daily (list[dict])
  • projects (list[dict])
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

receipts

Client.receipts(days=30, *, start=None, end=None)

Your finished sessions and what each cost: the last days, or between start and end.

See also: listReceipts in the HTTP API reference.

Request Syntax

receipts = cnx.receipts( days=30, # or start='2026-10-01', end='2026-10-31' )

Parameters

  • days (int)
  • start (date | datetime | str)
  • end (date | datetime | str)

Return type

list[Receipt]

Response Syntax

[ Receipt( instance='string', label='string', gpu='string', gpu_count=123, app='string', model='string', region='string', requested_at=datetime(2026, 10, 28, 9, 0), started_at=datetime(2026, 10, 28, 9, 0), ended_at=datetime(2026, 10, 28, 9, 0), used_minutes=123.0, booked_minutes=123, charged_cents=123, refunded_cents=123, net_cents=123, project='string', outcome='string', ), ]

Response Structure

A list of Receipt objects: A finished session and what it cost.

  • instance (str)
  • label (str | None)
  • gpu (str)
  • gpu_count (int)
  • app (str)
  • model (str | None)
  • region (str)
  • requested_at (datetime | None)
  • started_at (datetime | None)
  • ended_at (datetime | None)
  • used_minutes (float)
  • booked_minutes (int)
  • charged_cents (int)
  • refunded_cents (int)
  • net_cents (int) – What it cost in the end.
  • project (str | None)
  • outcome (str)
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

list_schedules

Client.list_schedules()

Your schedules.

See also: listSchedules in the HTTP API reference.

Request Syntax

schedules = cnx.list_schedules()

Parameters

None.

Return type

list[Schedule]

Response Syntax

[ Schedule( id='string', name='string', project_id='string', app='string', model='string', gpus=[...], region='string', timezone='string', windows=[...], skip_dates=[...], lead_minutes=123, paused_until=datetime(2026, 10, 28, 9, 0), paused=True|False, next_window_start=datetime(2026, 10, 28, 9, 0), next_window_end=datetime(2026, 10, 28, 9, 0), hours_per_month=123.0, estimated_cents_per_month=123, runs=[...], ), ]

Response Structure

A list of Schedule objects: A GPU that starts and stops by itself on set days and hours, with a project.

  • id (str)
  • name (str)
  • project_id (str)
  • app (str) – The app it launches.
  • model (str | None)
  • gpus (list[str]) – Acceptable GPUs, in order of preference; the first one free is used.
  • region (str)
  • timezone (str) – IANA, e.g. 'America/Los_Angeles'.
  • windows (list[dict]) – [{'days': [0..6], 'start': '08:00', 'end': '18:00'}], Monday = 0.
  • skip_dates (list[str]) – Local dates with no machine, e.g. '2026-12-25'.
  • lead_minutes (int) – Started this long before each window.
  • paused_until (datetime | None)
  • paused (bool)
  • next_window_start (datetime | None)
  • next_window_end (datetime | None)
  • hours_per_month (float)
  • estimated_cents_per_month (int | None) – At today's price of the first GPU.
  • runs (list[ScheduleRun]) – The latest windows, newest first.
    • window_start (datetime | None)
    • window_end (datetime | None)
    • state (str) – 'pending' | 'launched' | 'waiting_gpu' | 'covered' | 'skipped' | 'missed' | 'failed'.
    • instance (str | None)
    • attempts (int)
    • last_error (str | None)
  • raw (dict)

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

create_schedule

Client.create_schedule(name, *, project, app, gpus, timezone, windows, model=None, region='any', skip_dates=None, lead_minutes=15)

A GPU that starts by itself before each weekly window and stops at its end, with a project. Each window is charged like a launch of that length.

See also: createSchedule in the HTTP API reference.

Request Syntax

from computenexa import window schedule = cnx.create_schedule( 'Weekdays', project=Project|'string', app='chat', gpus=['l40s', 'a40'], timezone='America/Los_Angeles', windows=[window('mon-fri', '08:00', '18:00')], model='string', region='any'|'us'|'ca', skip_dates=['2026-12-25'], lead_minutes=15, )

Parameters

  • name (str) [REQUIRED]
  • project (Project | str) [REQUIRED] – Schedules always use a project.
  • app (str) [REQUIRED]
  • gpus (list[str]) [REQUIRED] – Acceptable GPUs in order of preference.
  • timezone (str) [REQUIRED] – IANA name.
  • windows (list[dict]) [REQUIRED] – Weekly windows; build them with window(days, start, end).
  • model (str)
  • region (str)
  • skip_dates (list[date | str]) – Local dates with no machine.
  • lead_minutes (int) – Start this long before each window. Default 15.

Return type

Schedule

Response Syntax

Schedule( id='string', name='string', project_id='string', app='string', model='string', gpus=[...], region='string', timezone='string', windows=[...], skip_dates=[...], lead_minutes=123, paused_until=datetime(2026, 10, 28, 9, 0), paused=True|False, next_window_start=datetime(2026, 10, 28, 9, 0), next_window_end=datetime(2026, 10, 28, 9, 0), hours_per_month=123.0, estimated_cents_per_month=123, runs=[...], )

Response Structure

Schedule: A GPU that starts and stops by itself on set days and hours, with a project.

  • id (str)
  • name (str)
  • project_id (str)
  • app (str) – The app it launches.
  • model (str | None)
  • gpus (list[str]) – Acceptable GPUs, in order of preference; the first one free is used.
  • region (str)
  • timezone (str) – IANA, e.g. 'America/Los_Angeles'.
  • windows (list[dict]) – [{'days': [0..6], 'start': '08:00', 'end': '18:00'}], Monday = 0.
  • skip_dates (list[str]) – Local dates with no machine, e.g. '2026-12-25'.
  • lead_minutes (int) – Started this long before each window.
  • paused_until (datetime | None)
  • paused (bool)
  • next_window_start (datetime | None)
  • next_window_end (datetime | None)
  • hours_per_month (float)
  • estimated_cents_per_month (int | None) – At today's price of the first GPU.
  • runs (list[ScheduleRun]) – The latest windows, newest first.
    • window_start (datetime | None)
    • window_end (datetime | None)
    • state (str) – 'pending' | 'launched' | 'waiting_gpu' | 'covered' | 'skipped' | 'missed' | 'failed'.
    • instance (str | None)
    • attempts (int)
    • last_error (str | None)
  • raw (dict)

Exceptions

  • InvalidRequestError
  • NotFoundError (project)
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError
  • ValueError (no GPUs)

update_schedule

Client.update_schedule(schedule, *, name, project, app, gpus, timezone, windows, model=None, region='any', skip_dates=None, lead_minutes=15)

Replace a schedule's settings: send them all, as for create_schedule.

See also: updateSchedule in the HTTP API reference.

Parameters

  • schedule (Schedule | str) [REQUIRED]
  • … () – As for create_schedule.

Return type

Schedule

Response Syntax

Schedule( id='string', name='string', project_id='string', app='string', model='string', gpus=[...], region='string', timezone='string', windows=[...], skip_dates=[...], lead_minutes=123, paused_until=datetime(2026, 10, 28, 9, 0), paused=True|False, next_window_start=datetime(2026, 10, 28, 9, 0), next_window_end=datetime(2026, 10, 28, 9, 0), hours_per_month=123.0, estimated_cents_per_month=123, runs=[...], )

Response Structure

Schedule: A GPU that starts and stops by itself on set days and hours, with a project.

  • id (str)
  • name (str)
  • project_id (str)
  • app (str) – The app it launches.
  • model (str | None)
  • gpus (list[str]) – Acceptable GPUs, in order of preference; the first one free is used.
  • region (str)
  • timezone (str) – IANA, e.g. 'America/Los_Angeles'.
  • windows (list[dict]) – [{'days': [0..6], 'start': '08:00', 'end': '18:00'}], Monday = 0.
  • skip_dates (list[str]) – Local dates with no machine, e.g. '2026-12-25'.
  • lead_minutes (int) – Started this long before each window.
  • paused_until (datetime | None)
  • paused (bool)
  • next_window_start (datetime | None)
  • next_window_end (datetime | None)
  • hours_per_month (float)
  • estimated_cents_per_month (int | None) – At today's price of the first GPU.
  • runs (list[ScheduleRun]) – The latest windows, newest first.
    • window_start (datetime | None)
    • window_end (datetime | None)
    • state (str) – 'pending' | 'launched' | 'waiting_gpu' | 'covered' | 'skipped' | 'missed' | 'failed'.
    • instance (str | None)
    • attempts (int)
    • last_error (str | None)
  • raw (dict)

Exceptions

  • NotFoundError
  • InvalidRequestError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

pause_schedule

Client.pause_schedule(schedule, until)

No machine starts before until. A machine already running keeps running.

See also: pauseSchedule in the HTTP API reference.

Request Syntax

schedule = cnx.pause_schedule( Schedule|'string', until=datetime(2026, 12, 1, 8, 0, tzinfo=...)|'2026-12-01T08:00:00-08:00', )

Parameters

  • schedule (Schedule | str) [REQUIRED]
  • until (datetime | str) [REQUIRED]

Return type

Schedule

Response Syntax

Schedule( id='string', name='string', project_id='string', app='string', model='string', gpus=[...], region='string', timezone='string', windows=[...], skip_dates=[...], lead_minutes=123, paused_until=datetime(2026, 10, 28, 9, 0), paused=True|False, next_window_start=datetime(2026, 10, 28, 9, 0), next_window_end=datetime(2026, 10, 28, 9, 0), hours_per_month=123.0, estimated_cents_per_month=123, runs=[...], )

Response Structure

Schedule: A GPU that starts and stops by itself on set days and hours, with a project.

  • id (str)
  • name (str)
  • project_id (str)
  • app (str) – The app it launches.
  • model (str | None)
  • gpus (list[str]) – Acceptable GPUs, in order of preference; the first one free is used.
  • region (str)
  • timezone (str) – IANA, e.g. 'America/Los_Angeles'.
  • windows (list[dict]) – [{'days': [0..6], 'start': '08:00', 'end': '18:00'}], Monday = 0.
  • skip_dates (list[str]) – Local dates with no machine, e.g. '2026-12-25'.
  • lead_minutes (int) – Started this long before each window.
  • paused_until (datetime | None)
  • paused (bool)
  • next_window_start (datetime | None)
  • next_window_end (datetime | None)
  • hours_per_month (float)
  • estimated_cents_per_month (int | None) – At today's price of the first GPU.
  • runs (list[ScheduleRun]) – The latest windows, newest first.
    • window_start (datetime | None)
    • window_end (datetime | None)
    • state (str) – 'pending' | 'launched' | 'waiting_gpu' | 'covered' | 'skipped' | 'missed' | 'failed'.
    • instance (str | None)
    • attempts (int)
    • last_error (str | None)
  • raw (dict)

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

resume_schedule

Client.resume_schedule(schedule)

Resume a paused schedule now.

See also: pauseSchedule in the HTTP API reference.

Request Syntax

schedule = cnx.resume_schedule( Schedule|'string', )

Parameters

  • schedule (Schedule | str) [REQUIRED]

Return type

Schedule

Response Syntax

Schedule( id='string', name='string', project_id='string', app='string', model='string', gpus=[...], region='string', timezone='string', windows=[...], skip_dates=[...], lead_minutes=123, paused_until=datetime(2026, 10, 28, 9, 0), paused=True|False, next_window_start=datetime(2026, 10, 28, 9, 0), next_window_end=datetime(2026, 10, 28, 9, 0), hours_per_month=123.0, estimated_cents_per_month=123, runs=[...], )

Response Structure

Schedule: A GPU that starts and stops by itself on set days and hours, with a project.

  • id (str)
  • name (str)
  • project_id (str)
  • app (str) – The app it launches.
  • model (str | None)
  • gpus (list[str]) – Acceptable GPUs, in order of preference; the first one free is used.
  • region (str)
  • timezone (str) – IANA, e.g. 'America/Los_Angeles'.
  • windows (list[dict]) – [{'days': [0..6], 'start': '08:00', 'end': '18:00'}], Monday = 0.
  • skip_dates (list[str]) – Local dates with no machine, e.g. '2026-12-25'.
  • lead_minutes (int) – Started this long before each window.
  • paused_until (datetime | None)
  • paused (bool)
  • next_window_start (datetime | None)
  • next_window_end (datetime | None)
  • hours_per_month (float)
  • estimated_cents_per_month (int | None) – At today's price of the first GPU.
  • runs (list[ScheduleRun]) – The latest windows, newest first.
    • window_start (datetime | None)
    • window_end (datetime | None)
    • state (str) – 'pending' | 'launched' | 'waiting_gpu' | 'covered' | 'skipped' | 'missed' | 'failed'.
    • instance (str | None)
    • attempts (int)
    • last_error (str | None)
  • raw (dict)

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

delete_schedule

Client.delete_schedule(schedule)

No more machines start; one running now keeps running until its window ends (or you stop it).

See also: deleteSchedule in the HTTP API reference.

Request Syntax

cnx.delete_schedule( Schedule|'string', )

Parameters

  • schedule (Schedule | str) [REQUIRED]

Return type

None

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

computenexa.window

computenexa.window(days, start, end)

A weekly window for a schedule. days: 'mon-fri', 'sat,sun', 'fri-mon' (wraps over the weekend) or [0, 2, 4] (Monday = 0). Times in the schedule's time zone; start before end on the same day.

Request Syntax

from computenexa import window w = window('mon-fri', '08:00', '18:00')

Parameters

  • days (str | list[int]) [REQUIRED]
  • start (str) [REQUIRED]
  • end (str) [REQUIRED]

Return type

dict

Returns

{'days': [0, 1, 2, 3, 4], 'start': '08:00', 'end': '18:00'}

Exceptions

  • ValueError (unknown day)

Instance.refresh

Instance.refresh()

Fetch the machine's current state, in place.

See also: getInstance in the HTTP API reference.

Request Syntax

machine.refresh()

Parameters

None.

Return type

Instance

Returns

The same object, updated.

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Instance.wait_until_running

Instance.wait_until_running(timeout=900, poll=10, on_progress=None)

Wait until the machine is running.

Request Syntax

machine.wait_until_running( timeout=900, poll=10, on_progress=lambda m: print(m.state, m.startup_progress), )

Parameters

  • timeout (float) – Seconds before giving up. Default 900.
  • poll (float) – Seconds between checks. Default 10.
  • on_progress (callable) – Called with the machine after each check.

Return type

Instance

Returns

The same object, running.

Exceptions

  • LaunchFailedError (couldn't start; refunded in full)
  • WaitTimeoutError (it may still start: check or stop it)
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Instance.extend

Instance.extend(minutes=None, *, hours=None)

Add time at the price it launched with.

See also: extendInstance in the HTTP API reference.

Request Syntax

machine.extend(hours=1)

Parameters

  • minutes (int)
  • hours (float)

Return type

Instance

Returns

The same object, updated.

Exceptions

  • InsufficientCreditsError
  • ConflictError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Instance.stop

Instance.stop()

End it now: stop if running, cancel if still starting. Unused time is refunded.

Request Syntax

machine.stop()

Parameters

None.

Return type

Instance

Returns

The same object, updated (see refunded_cents).

Exceptions

  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Instance.api_key

Instance.api_key()

The machine's own Model API (or Voice Agent API) key, for api_base_url. Machines you launched; it stops working when the machine stops.

See also: getInstanceApiKey in the HTTP API reference.

Request Syntax

key = machine.api_key()

Parameters

None.

Return type

str

Returns

The key.

Exceptions

  • NotFoundError
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Instance.app_url

Instance.app_url(app)

A one-time, signed-in link that opens one of the machine's browser apps. Machines you launched.

See also: openInstanceApp in the HTTP API reference.

Request Syntax

url = machine.app_url( 'chat'|'jupyter'|..., )

Parameters

  • app (str) [REQUIRED]

Return type

str

Returns

The link (works once, soon after it's made).

Exceptions

  • NotFoundError
  • ConflictError (not running)
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Instance.save_project

Instance.save_project()

Save the machine's project now instead of at the next automatic save (within about 30 seconds).

See also: saveInstanceProject in the HTTP API reference.

Request Syntax

machine.save_project()

Parameters

None.

Return type

None

Exceptions

  • ConflictError (no project, or not running)
  • AuthenticationError
  • PermissionDeniedError
  • RateLimitError
  • ServerError
  • APIConnectionError

Catalog.available

Catalog.available(app=None)

GPUs for sale right now, cheapest first; only those that run app if given.

Request Syntax

gpus = catalog.available( app='chat', )

Parameters

  • app (str)

Return type

list[Gpu]

Returns

See Catalog.gpus.

App.recommended_model

App.recommended_model(vram_gb)

Our model pick for a GPU with this much memory, or None.

Request Syntax

model = catalog.apps['chat'].recommended_model( vram_gb=48, )

Parameters

  • vram_gb (int) [REQUIRED]

Return type

str | None

Returns

A model name for launch(model=...).

Instance

computenexa.Instance

A GPU machine. Its methods (refresh, wait_until_running, extend, stop) act on it.

Attributes

  • id (str) – Its id, e.g. 'cnx-7f3a9c'.
  • state (str) – 'requested' | 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed'.
  • gpu (str) – The GPU's slug, e.g. 'rtx-4090'.
  • gpu_count (int) – GPUs in the machine.
  • app (str) – Its app (image family): 'basic', 'datascience', 'chat', 'imagegen', 'modelapi' or 'voice'.
  • label (str | None) – The name you gave it.
  • price_per_hour_cents (int) – Its price per hour, locked at launch, in US cents.
  • ssh_command (str | None) – How to connect, while running (when your account has an SSH key).
  • expires_at (datetime | None) – When its booked time ends (UTC).
  • time_left_seconds (int | None) – Time left, while running.
  • charged_cents (int) – What its launch and extensions cost.
  • refunded_cents (int) – Unused time given back.
  • cost_so_far_cents (int) – What it costs if it ended now.
  • end_reason (str | None) – Why it ended, e.g. 'user_stopped', 'expired', 'team_stopped', 'no_capacity'.
  • startup_progress (str | None) – What it's doing while it starts.
  • api_base_url (str | None) – Model API and Voice Agent machines, while running: their API address (key: api_key()).
  • is_running (bool) – state == 'running'.
  • is_active (bool) – Starting or running: it may still cost money.
  • raw (dict) – The full API reply.

Project

computenexa.Project

Saved storage, restored into ~/work on GPUs launched with it and saved back automatically.

Attributes

  • id (str) – Pass it (or the Project) as project= when launching.
  • name (str)
  • bytes_used (int) – Size of its files.
  • files (int) – Number of files.
  • created_at (datetime | None)
  • last_used_at (datetime | None)
  • in_use_by (str | None) – The machine using it right now, if any.
  • raw (dict)

Account

computenexa.Account

Who the API key acts as, and their team.

Attributes

  • id (str)
  • email (str)
  • balance_cents (int) – The team's balance, in US cents.
  • balance (float) – The same, in US dollars.
  • max_concurrent_gpus (int) – How many GPUs the team can run at once.
  • organization (Organization)
    • id (str)
    • name (str)
    • role (str) – Your role: 'owner' | 'admin' | 'member'.
    • members (int)
  • raw (dict)

Catalog

computenexa.Catalog

GPUs with live prices and stock, and the apps they run.

Attributes

  • region (str) – 'any', 'us' or 'ca'.
  • gpus (list[Gpu])
    • slug (str) – What you launch with, e.g. 'rtx-4090'.
    • name (str) – e.g. 'NVIDIA RTX 4090'.
    • vram_gb (int)
    • available (bool) – For sale right now.
    • price_per_hour_cents (int | None) – None when not for sale right now.
    • billing_unit (str) – 'minute', or 'hour' (billed per started hour).
    • apps (list[str]) – The apps it runs.
    • regions (list[str])
  • apps (dict[str, App])
    • name (str) – The value for app=.
    • display_name (str) – As on the launch page.
    • summary (str)
    • needs_ssh_key (bool)
    • models (list[dict]) – Models offered: name, label, size_gb, min_vram_gb, note, licence, gated.
    • model_required (bool)
    • recommended (list[tuple[int, str]]) – (min GPU memory in GB, model); first match wins.
  • raw (dict)

SshKey

computenexa.SshKey

A public SSH key that can log in to your machines.

Attributes

  • id (str)
  • name (str)
  • fingerprint (str)
  • raw (dict)

Schedule

computenexa.Schedule

A GPU that starts and stops by itself on set days and hours, with a project.

Attributes

  • id (str)
  • name (str)
  • project_id (str)
  • app (str) – The app it launches.
  • model (str | None)
  • gpus (list[str]) – Acceptable GPUs, in order of preference; the first one free is used.
  • region (str)
  • timezone (str) – IANA, e.g. 'America/Los_Angeles'.
  • windows (list[dict]) – [{'days': [0..6], 'start': '08:00', 'end': '18:00'}], Monday = 0.
  • skip_dates (list[str]) – Local dates with no machine, e.g. '2026-12-25'.
  • lead_minutes (int) – Started this long before each window.
  • paused_until (datetime | None)
  • paused (bool)
  • next_window_start (datetime | None)
  • next_window_end (datetime | None)
  • hours_per_month (float)
  • estimated_cents_per_month (int | None) – At today's price of the first GPU.
  • runs (list[ScheduleRun]) – The latest windows, newest first.
    • window_start (datetime | None)
    • window_end (datetime | None)
    • state (str) – 'pending' | 'launched' | 'waiting_gpu' | 'covered' | 'skipped' | 'missed' | 'failed'.
    • instance (str | None)
    • attempts (int)
    • last_error (str | None)
  • raw (dict)

Receipt

computenexa.Receipt

A finished session and what it cost.

Attributes

  • instance (str)
  • label (str | None)
  • gpu (str)
  • gpu_count (int)
  • app (str)
  • model (str | None)
  • region (str)
  • requested_at (datetime | None)
  • started_at (datetime | None)
  • ended_at (datetime | None)
  • used_minutes (float)
  • booked_minutes (int)
  • charged_cents (int)
  • refunded_cents (int)
  • net_cents (int) – What it cost in the end.
  • project (str | None)
  • outcome (str)
  • raw (dict)

Usage

computenexa.Usage

Your GPU use and spending over a period.

Attributes

  • days (int)
  • balance_cents (int)
  • spend_cents (int)
  • topups_cents (int)
  • sessions (int)
  • gpu_hours (float)
  • by_gpu (list[dict])
  • by_image (list[dict])
  • daily (list[dict])
  • projects (list[dict])
  • raw (dict)

ModelApiAddress

computenexa.ModelApiAddress

Your team's stable Model API address: the same on every launch, pointing at the newest running Model API machine.

Attributes

  • handle (str)
  • base_url (str) – https://<handle>-api.computenexa-apps.com/v1
  • instance (str | None) – The machine it points at now.
  • raw (dict)

LedgerEntry

computenexa.LedgerEntry

A charge, refund or top-up.

Attributes

  • created_at (datetime | None)
  • kind (str) – 'topup' | 'charge' | 'refund' | 'adjustment'.
  • amount_cents (int) – + credit, − debit.
  • description (str)
  • instance (str | None) – The machine it's for, if any.
  • raw (dict)

Exceptions

from computenexa import NoCapacityError, …

Every error is a subclass of ComputeNexaError, with message (safe to show), status (HTTP), code (stable, e.g. "no_capacity") and request_id (quote it to support@computenexa.com).

ExceptionWhen
ComputeNexaErrorBase class of every error. Has message, status, code and request_id.
InsufficientCreditsError402: not enough credits for the launch or extension.
NoCapacityError409 no_capacity: that GPU is fully booked right now.
GpuLimitReachedError409 gpu_limit_reached: your team (or you) already run as many GPUs as allowed.
ProjectInUseError409 project_in_use: another GPU is using the project.
ConflictError409: other clashes with the current state (e.g. extending a machine that isn't running).
AuthenticationError401: the key is missing, mistyped or revoked, or its creator left the team.
PermissionDeniedError403: a look-only key tried to change something, or a dashboard-only setting.
NotFoundError404: no such machine, project or key, or not one you can see.
InvalidRequestError422: a field is missing or wrong.
RateLimitError429: more than 120 requests a minute (retried first).
ServerError5xx: a problem on our side (reads are retried first).
APIConnectionErrorThe API couldn't be reached.
LaunchFailedErrorThe machine couldn't start; refunded in full.
WaitTimeoutErrorwait_until_running gave up; the machine may still start.