SDK Reference
v0.1.1

Commutator SDK

The Commutator Studios SDK is an intuitive wrapper designed for developers and researchers. Instead of invoking HTTP endpoints manually, you can interact with jobs, optimizer models, and quantum hardware backends natively within your environments.

Installation

Install the official package:

pip install commutator-sdk
Quickstart Example
from commutator import CommutatorClient

client = CommutatorClient(
    api_key="your_api_key"
)

# Start working
jobs = client.jobs.list()

Authentication

Authentication

Initialize SDK Client

CommutatorClient(api_key: str)

Initialize the SDK client using your Commutator API Key generated from your Dashboard (Dashboard -> API Access). Environment endpoints (production, staging, demo, local) are automatically resolved based on your API key prefix (`cs_live_*`, `cs_stage_*`, `cs_demo_*`, `cs_loc_*`). Note: IBM credentials must be added through your Dashboard (Settings -> Credentials) prior to running hardware workloads.

Parameters

api_key(string)required
Your Commutator API key
from commutator import CommutatorClient

# Initialize with API Key generated from Dashboard
client = CommutatorClient(api_key="cs_live_abc123...")

Backend

Backend

List Quantum Backends

client.backends.list() -> List[Dict]

Query the available quantum processors, physical qubits count, and current availability status.

backends = client.backends.list()
for backend in backends:
    print(backend["name"], backend["status"])
Backend

Toggle Backend Status

client.backends.activate(backend_id: str, enabled: bool = True) -> bool

Toggle or set activation status of a specific reserved backend processor.

Parameters

backend_id(string)required
The unique identifier of the backend
enabled(boolean)
Set to True to activate or False to deactivate (default: True)
client.backends.activate(backend_id="550e8400-e29b-41d4-a716-446655440000", enabled=True)

Optimizer

Optimizer

Predict Performance

client.optimizer.recommend(job_id: str, target_backends: List[str] = None) -> Dict

Submits a hardware recommendation calculation job. Returns an immediate job submission response with jobId and jobStatus.

Parameters

job_id(string)required
Target job UUID created during workload submission
target_backends(List[str])
Optional list of proposed target backend processors
res = client.optimizer.recommend(job_id="550e8400-e29b-41d4-a716-446655440000", target_backends=["ibm_kyiv"])
Optimizer

Poll Recommendation Progress

client.optimizer.get_status(job_id: str) -> Dict

Poll progress and retrieve completed recommendations for an optimization job, including total count, completion percentage, and expiration timestamp (validUntil).

Parameters

job_id(string)required
Target job UUID of the recommendation calculation job
report = client.optimizer.get_status(job_id="550e8400-e29b-41d4-a716-446655440000")

Job

Job

List Algorithms

client.jobs.list_algorithms() -> List[str]

Retrieve the list of supported quantum algorithms available for execution.

algorithms = client.jobs.list_algorithms()
print("Supported:", algorithms)
Job

submit_job

client.jobs.submit_job(name: str, algorithm: str, file_path: str, backend: str = "ibm_fez", dynamic_decoupling: bool = False, optimization_level: int = 3) -> dict

Submits an integrated VQE execution job. Uploads the configuration artifact and registers the job record in one atomic operation.

Parameters

name(string)required
Job display name.
algorithm(string)required
Target algorithm (e.g. "VQE").
file_path(string)required
Path to local JSON configuration file.
backend(string)
Target backend identifier (defaults to "ibm_fez").
dynamic_decoupling(boolean)
Enable dynamic decoupling sequence.
optimization_level(integer)
Transpilation optimization level (0-3).
vqe_job = client.jobs.submit_job(
    name="VQE Hydrogen Molecule",
    algorithm="VQE",
    file_path="circuit.json",
    backend="ibm_fez",
    optimization_level=3
)
Job

List Quantum Jobs

client.jobs.list(limit: int = None, offset: int = None, cursor: str = None, include_pagination: bool = False) -> Union[List[Dict], Dict]

Retrieve the job list history and status for the authenticated user. Pass include_pagination=True to return the full payload with pagination metadata (total, nextCursor, hasMore).

Parameters

limit(integer)
Max number of jobs to fetch per chunk (e.g. 10).
offset(integer)
Number of jobs to skip for page-based chunking (e.g. 0).
cursor(string)
Job ID pointer to fetch items created after.
include_pagination(boolean)
Set to True to return {"data": [...], "pagination": {total, nextCursor, hasMore}}.
# Simple job list:
jobs = client.jobs.list(limit=10, offset=0)

# With pagination metadata:
res = client.jobs.list(limit=10, offset=0, include_pagination=True)
print("Total:", res["pagination"]["total"])
print("Next Cursor:", res["pagination"]["nextCursor"])
Job

Save Job Draft

client.jobs.create(name: str, algorithm: str, file_path: str, **kwargs) -> dict

Creates a new quantum job draft. Returns the Job object with its assigned ID and initial Created status.

Parameters

name(string)required
Descriptive name of the quantum job
algorithm(string)required
Algorithm identifier (e.g. "VQE")
file_path(string)required
Local path to the JSON configuration file.
new_job = client.jobs.create(
    name="VQE Hydrogen Molecule",
    algorithm="VQE",
    file_path="circuit.json"
)
Job

Get Job Results

client.jobs.get(job_id: str) -> Job

Retrieve complete metadata, configuration, and current status of a specific job.

Parameters

job_id(string)required
The unique UUID of the job
job = client.jobs.get("77df8264-74d7-478d-b1b2-57ce96891161")
print(job["status"]) # Returns 'CREATED', 'PENDING', or 'COMPLETED'
Job

Run Saved Job

client.jobs.execute(job_id: str, backend: str, optimization_level: int = 3, dynamic_decoupling: bool = False, max_iterations: int = None, convergence: float = None, predicted_shots: int = None, **kwargs) -> dict

Executes a previously created job on the specified quantum backend. Accepts hardware backend selection, transpilation optimization level, dynamic decoupling, maximum iterations, and convergence parameters.

Parameters

job_id(string)required
The ID of the job to execute
backend(string)required
Target quantum backend name (e.g. "ibm_kyiv")
optimization_level(integer)
Circuit optimization level (0-3, default: 3)
dynamic_decoupling(boolean)
Enable dynamic decoupling sequence (default: False)
max_iterations(integer)
Maximum optimization iterations (e.g. 100)
convergence(float)
Convergence threshold (e.g. 0.001)
predicted_shots(integer)
Target shot count for QPU execution (e.g. 1024)
job_execution = client.jobs.execute(
    job_id=new_job["id"],
    backend="ibm_kyiv",
    optimization_level=3,
    max_iterations=100,
    convergence=0.001
)
Job

Delete Job

client.jobs.delete(job_id: str) -> bool

Delete or cancel a specific quantum job. Returns True if successfully deleted.

Parameters

job_id(string)required
The unique UUID of the job to delete
success = client.jobs.delete("77df8264-74d7-478d-b1b2-57ce96891161")
print("Deleted:", success)
Job

Download Results

client.jobs.download_results(job_id: str) -> Dict[str, Any]

Download the calculated mathematical eigenvalues or optimized quantum result data.

Parameters

job_id(string)required
The unique UUID of the job
results = client.jobs.download_results("77df8264-74d7-478d-b1b2-57ce96891161")
print("Energy eigenvalue:", results.get("energy"))

Administration

Administration

List Team Members

client.admin.get_team() -> Dict

Retrieve details about your current organization/team and quota limits.

team = client.admin.get_team()
print("Team Name:", team["name"])
Administration

List Audit Logs

client.identity.get_audit_logs(limit: int = 50, offset: int = 0, cursor: str = None, include_pagination: bool = False) -> Union[List[Dict], Dict]

Retrieve recent security and access audit logs for the team. Pass include_pagination=True to receive pagination metadata (total, nextCursor, hasMore).

Parameters

limit(integer)
Max number of log entries to retrieve
offset(integer)
Number of log entries to skip for pagination
cursor(string)
Cursor ID pointer to fetch items created after
include_pagination(boolean)
Set to True to return {"data": [...], "pagination": {total, nextCursor, hasMore}}
# Simple list:
logs = client.identity.get_audit_logs(limit=10, offset=0)

# With pagination metadata:
res = client.identity.get_audit_logs(limit=10, offset=0, include_pagination=True)
print("Total logs:", res["pagination"]["total"])