QCOSClient Reference

Complete API reference for the QCOS Python client.

Class: QCOSClient

The main synchronous client for interacting with QCOS.

Constructor

QCOSClient(
    api_key: str | None = None,
    api_url: str = "https://api.softquantus.com",
    timeout: int = 60,
    max_retries: int = 3,
    retry_delay: float = 1.0,
    log_level: str = "INFO",
)

Parameters:

Parameter	Type	Default	Description
api_key	str | None	None	API key. Falls back to QCOS_API_KEY env var
api_url	str	"https://api.softquantus.com"	API endpoint URL
timeout	int	60	Request timeout in seconds
max_retries	int	3	Number of retry attempts on failure
retry_delay	float	1.0	Initial delay between retries (exponential backoff)
log_level	str	"INFO"	Logging level: DEBUG, INFO, WARNING, ERROR

Example:

from qcos import QCOSClient

# Using environment variable
client = QCOSClient()

# Explicit configuration
client = QCOSClient(
    api_key="qcos-xxxx-xxxx",
    timeout=120,
    max_retries=5,
    log_level="DEBUG"
)

---

execute()

Execute a quantum circuit and wait for results.

def execute(
    qasm: str,
    shots: int = 1024,
    wait: bool = True,
    timeout: int | None = None,
    priority: int = 0,
) -> ExecutionResult

Parameters:

Parameter	Type	Default	Description
qasm	str	required	OpenQASM 2.0 circuit string
shots	int	1024	Number of measurement shots
wait	bool	True	Wait for completion
timeout	int | None	None	Override default timeout
priority	int	0	Job priority (enterprise only)

Returns: ExecutionResult

Raises:

• CircuitError - Invalid circuit syntax
• QuotaExceededError - Exceeds tier limits
• TimeoutError - Execution timed out

Example:

result = client.execute(
    qasm="""
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[2];
    creg c[2];
    h q[0];
    cx q[0],q[1];
    measure q -> c;
    """,
    shots=2048
)
print(result.counts)

---

submit()

Submit a circuit without waiting for completion.

def submit(
    qasm: str,
    shots: int = 1024,
    priority: int = 0,
) -> Job

Returns: Job object for tracking

Example:

job = client.submit(qasm=circuit, shots=1024)
print(f"Job ID: {job.job_id}")

# Later...
result = client.get_result(job.job_id)

---

get_status()

Get the status of a submitted job.

def get_status(job_id: str) -> JobStatus

Returns: JobStatus with fields:

• job_id: str
• status: str - "queued", "processing", "completed", "failed"
• created_at: datetime | None
• estimated_completion: datetime | None

Example:

status = client.get_status("abc123")
print(f"Status: {status.status}")

---

get_result()

Get the result of a completed job.

def get_result(
    job_id: str,
    wait: bool = False,
    timeout: int = 60,
) -> ExecutionResult

Example:

# Get immediately (error if not complete)
result = client.get_result("abc123")

# Wait for completion
result = client.get_result("abc123", wait=True, timeout=120)

---

execute_qiskit()

Execute a Qiskit QuantumCircuit.

def execute_qiskit(
    circuit: QuantumCircuit,
    shots: int = 1024,
    **kwargs
) -> ExecutionResult

Example:

from qiskit import QuantumCircuit

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

result = client.execute_qiskit(qc, shots=1024)

---

execute_cirq()

Execute a Cirq Circuit.

def execute_cirq(
    circuit: cirq.Circuit,
    shots: int = 1024,
    **kwargs
) -> ExecutionResult

---

execute_file()

Execute a circuit from a file.

def execute_file(
    path: str | Path,
    shots: int = 1024,
    **kwargs
) -> ExecutionResult

Example:

result = client.execute_file("circuits/bell.qasm", shots=2048)

---

batch_submit()

Submit multiple circuits as a batch.

def batch_submit(
    circuits: list[dict],
    parallel: bool = True,
) -> Batch

Example:

circuits = [
    {"qasm": circuit1, "shots": 1024},
    {"qasm": circuit2, "shots": 2048},
]

batch = client.batch_submit(circuits)
results = batch.wait_all()

---

get_user_info()

Get current user information and usage.

def get_user_info() -> UserInfo

Returns: UserInfo with fields:

• user_id: str
• email: str
• tier: str
• daily_limit: int
• jobs_today: int
• max_qubits: int
• max_shots: int

---

health()

Check API health status.

def health() -> dict

Returns:

{
    "status": "healthy",
    "version": "1.0.0",
    "queue_connected": True
}

---

Class: AsyncQCOSClient

Async version of the client for high-throughput applications.

from qcos import AsyncQCOSClient

async with AsyncQCOSClient() as client:
    result = await client.execute(qasm=circuit, shots=1024)

All methods are async versions of QCOSClient methods.

---

Class: ExecutionResult

Result of a circuit execution.

Properties

Property	Type	Description
job_id	str	Unique job identifier
status	str	Execution status
counts	dict[str, int]	Measurement counts
num_qubits	int	Number of qubits
shots	int	Shots executed
execution_time	float	Time in seconds
backend	str	Backend used
device	str	Device type
created_at	datetime	Submission time
completed_at	datetime	Completion time

Methods

# Get probabilities
probs = result.probabilities()
# {'00': 0.5, '11': 0.5}

# Get most likely state
state = result.most_likely()
# '00'

# Export
data = result.to_dict()
json_str = result.to_json()

# Save to file
result.save("result.json")

---

Class: Job

Represents a submitted job.

job = client.submit(qasm=circuit, shots=1024)

# Properties
job.job_id          # str: Job identifier
job.status          # str: Current status
job.created_at      # datetime: Submission time

# Methods
result = job.wait()           # Wait for completion
result = job.wait(timeout=60) # With timeout
status = job.refresh()        # Update status
job.cancel()                  # Cancel job (if queued)

---

Exceptions

from qcos import (
    QCOSError,           # Base exception
    AuthenticationError,  # Invalid API key
    RateLimitError,       # Too many requests
    QuotaExceededError,   # Tier limit exceeded
    CircuitError,         # Invalid circuit
    TimeoutError,         # Execution timeout
    ServerError,          # API server error
)

Exception Properties

try:
    result = client.execute(qasm=circuit, shots=1024)
except RateLimitError as e:
    e.message           # Error message
    e.reset_time        # datetime: When limit resets
    e.retry_after       # int: Seconds to wait

except QuotaExceededError as e:
    e.message           # Error message
    e.limit             # int: Your limit
    e.requested         # int: What you requested
    e.resource          # str: 'qubits', 'shots', 'jobs'

except CircuitError as e:
    e.message           # Error message
    e.line              # int: Line number
    e.column            # int: Column number
    e.details           # str: Detailed explanation