qcoscloud Python SDK: run quantum, GPU and CPU workloads from code

qcoscloud is one client for everything the platform sells: prepaid credits, quantum instances, and workloads on the simulator, real QPUs (via QCOS) and on-demand GPU/CPU — all over a single prepaid wallet. The SDK never touches a cloud or a provider credential; it authenticates with your sq-live- key and the platform Execution Plane authorizes, meters and settles every call.

Install

PyPI publishing is in progress — until the qcoscloud release lands on PyPI, use the REST API directly (the SDK is a thin wrapper over it, so you lose nothing). Every example on this page applies unchanged the moment the package is published.

pip install qcoscloud            # once the PyPI release is live
pip install "qcoscloud[mcp]"     # with the MCP server for AI agents

Python 3.10+; the only runtime dependency is httpx. The qcoscloud CLI is installed as a console script by the same package.

Authenticate

export QCOSCLOUD_API_KEY=sq-live-...                     # console → API Keys
export QCOSCLOUD_URL=https://platform.softquantus.com    # optional; this is the default

from qcoscloud import QCOSCloud

qc = QCOSCloud()                          # reads QCOSCLOUD_API_KEY / QCOSCLOUD_URL
# or explicitly:
qc = QCOSCloud(api_key="sq-live-...", base_url="https://platform.softquantus.com")

Constructor: QCOSCloud(api_key=None, base_url=None, timeout=60.0). A missing key raises QCOSCloudError immediately.

Method reference

Method	Returns	What it does
`credits()`	`float`	Prepaid wallet balance (1 credit = 0.01)
`add_credits_url()`	`str`	Deep link to the console Billing page
`computers()`	`list[dict]`	QPU devices reachable via QCOS
`targets()`	`list[dict]`	Compute activated for your workspace (sim, `cpu.`, `gpu.`, QPUs)
`instances()`	`list[dict]`	Your quantum instances
`create_instance(name, *, plan, qpus, access_group)`	`dict`	Create an instance
`run(target, *, shots, instance, mode, workload, qasm, max_cost_usd, max_runtime_seconds, idempotency_key)`	`dict`	Submit any workload to a target
`simulate(*, shots, instance, qasm)`	`dict`	Run a circuit on the free simulator
`gpu_job(*, gpu, command, minutes, num_gpus, instance, image)`	`dict`	On-demand GPU batch job
`cpu_job(*, tier, command, minutes, cpus, instance, image)`	`dict`	On-demand CPU batch job
`workload(job_id)`	`dict`	One job’s status and cost
`evidence(job_id)`	`dict`	The settled job’s Evidence Bundle
`cancel(job_id)`	`dict`	Cancel; releases the unused reservation
`workloads(page_size=20)`	`list[dict]`	Recent runs

Every failed call raises QCOSCloudError carrying .status (HTTP code) and .reason (machine reason such as insufficient_credits) — see error handling.

Credits and catalog

qc.credits()          # -> 125.0   (prepaid balance; 1 credit = 0.01)
qc.add_credits_url()  # -> 'https://platform.softquantus.com/#billing'

qc.computers()        # QPU devices via QCOS
qc.targets()          # everything activated for your workspace

targets() also activates the workspace’s default catalog (simulator + GPU/CPU tiers) on first call, so it is a good first request from a fresh workspace.

Instances

An instance = pricing plan + allowed computers + access group. Pass instance= on a run to bill through it; omit it for plain prepaid billing.

qc.create_instance(
    "research",
    plan="prepaid",                       # "free" | "prepaid" | "paygo"
    qpus=["qcos.simulator.statevector"],  # allowed targets ([] = all entitled)
    access_group="all_members",           # or "owners_only" / "custom"
)
qc.instances()

Run a circuit

run() is the general entry point: target picks the backend, the circuit is OpenQASM 2/3 passed as qasm= (the SDK wraps it into a QUANTUM_CIRCUIT workload for you):

BELL = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;'

job = qc.run("qcos.simulator.statevector", qasm=BELL, shots=1024)
# {'job_id': 'job_...', 'status': 'CREDIT_RESERVED', 'estimated_cost_usd': 0.0, ...}

qc.workload(job["job_id"])   # poll until 'status': 'SETTLED'

simulate() is a convenience that targets the free simulator:

qc.simulate(qasm=BELL, shots=1024)        # free run of YOUR circuit

A circuit is required: calling run()/simulate() without qasm= (or a workload carrying one) submits an empty QUANTUM_CIRCUIT and the API rejects it with 422 quantum_circuit_missing before reserving anything. Always pass your QASM.

To target a real QPU, use its device id and guard the spend:

job = qc.run(
    "<qpu-device-id>",                # pick one from qc.computers()
    qasm=BELL,
    shots=2000,
    instance="research",
    max_cost_usd=5.0,                 # reject before running if the estimate exceeds this
)

mode="QCOS_OPTIMIZED" applies QCOS transforms and requires an active QCOS license (qcos_license_required otherwise). Default is "NATIVE".
Real QPU runs require the workspace to be entitled to the device and your instance to allow it; otherwise you get no_active_entitlement_for_offer, instance_access_denied or (on a free instance) free_plan_simulators_only — and nothing is charged.
Every run() sends an Idempotency-Key (a fresh UUID by default), so a network retry can never double-submit. Pass idempotency_key= to control it.

GPU and CPU jobs

Both run a container command with per-minute billing and a mandatory runtime bound — the worst case is reserved up front and the machine is stopped when the reservation is exhausted, so a job can never overspend:

job = qc.gpu_job(
    gpu="a100-80gb",                 # -> target "gpu.a100-80gb"
    command="python train.py",
    minutes=30,                      # runtime bound (reserved worst case)
    num_gpus=1,
    instance="research",
    image=None,                      # optional container image
)

job = qc.cpu_job(
    tier="16vcpu",                   # -> target "cpu.16vcpu"
    command="python big_sim.py",
    minutes=60,
    cpus=16,
)

If GPU/CPU capacity is not available for your workspace the call fails closed with gpu_provider_unavailable (503) and no money is held. Rates are in Backends & pricing.

Poll, cancel, list

qc.workload(job["job_id"])   # {'job_id': ..., 'status': 'SETTLED', 'actual_cost_usd': ..., 'result_verified': True}
qc.cancel(job["job_id"])     # stop + release any unused reservation
qc.workloads()               # recent runs

Status progresses CREDIT_RESERVED → SUBMITTING → SUBMITTED → RUNNING → SETTLED (or FAILED / CANCELLED). On a settled job, result_verified and usage_metrics are populated and the Evidence Bundle is available over REST.

Error handling

from qcoscloud import QCOSCloud, QCOSCloudError

try:
    qc.run("qcos.simulator.statevector", qasm=BELL, shots=100000)
except QCOSCloudError as e:
    print(e.status)   # e.g. 402
    print(e.reason)   # e.g. 'insufficient_credits'
    print(str(e))     # includes a human hint, e.g. "... top up with the console Billing page."

e.reason is the platform’s machine reason — branch on it, never on the message text. The full catalog is in Errors & refusal reasons.

MCP server (for AI agents)

The same operations are exposed as MCP tools so an AI agent (Claude Desktop, Cursor, or any MCP client) can drive compute on your wallet with the same guardrails — the agent never sees a cloud or a raw credential beyond the key you configure:

pip install "qcoscloud[mcp]"             # once the PyPI release is live
export QCOSCLOUD_API_KEY=sq-live-...
python -m qcoscloud.mcp_server           # stdio MCP server

Tools: get_credits, list_computers, list_targets, list_instances, create_instance, run_simulation, run_qpu_job, run_gpu_job, run_cpu_job, get_workload, get_evidence, cancel_workload. The circuit tools (run_simulation, run_qpu_job) take the OpenQASM source as their qasm argument — the same 422 quantum_circuit_missing gate applies if an agent omits it. Errors come back as values ({"error": ..., "reason": ...}) so the agent can read the machine reason and react.

Console

Run compute

API & clients

Trust & ecosystem

qcoscloud Python SDK: run quantum, GPU and CPU workloads from code

Install

Authenticate

Method reference

Credits and catalog

Instances

Run a circuit

GPU and CPU jobs

Poll, cancel, list

Error handling

MCP server (for AI agents)

​Install

​Authenticate

​Method reference

​Credits and catalog

​Instances

​Run a circuit

​GPU and CPU jobs

​Poll, cancel, list

​Error handling

​MCP server (for AI agents)

Install

Authenticate

Method reference

Credits and catalog

Instances

Run a circuit

GPU and CPU jobs

Poll, cancel, list

Error handling

MCP server (for AI agents)