QCOS Benchmarking API

Complete documentation for the QCOS Benchmarking API. This API enables operational validation and performance verification of quantum backends.

Overview

The Benchmarking API allows you to:

• Run standardized benchmarks across quantum backends
• Generate verifiable evidence for compliance and auditing
• Compare performance across providers (IBM, AWS, Azure)
• Validate quantum hardware before production workloads

---

Base URL

https://api.softqcos.softquantus.com/api/v2/bench

Authentication

All endpoints require authentication via the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
     https://api.softqcos.softquantus.com/api/v2/bench/workloads

---

Endpoints

List Available Workloads

Get all available benchmark workloads.

GET /api/v2/bench/workloads

Response:

{
  "workloads": [
    {
      "id": "bell_state",
      "type": "BELL_STATE",
      "description": "Bell state preparation (2 qubits)",
      "qubits": 2
    },
    {
      "id": "ghz_5q",
      "type": "GHZ_SCALING",
      "description": "GHZ state (5 qubits)",
      "qubits": 5
    },
    {
      "id": "ghz_10q",
      "type": "GHZ_SCALING",
      "description": "GHZ state (10 qubits)",
      "qubits": 10
    },
    {
      "id": "ghz_50q",
      "type": "GHZ_SCALING",
      "description": "GHZ state (50 qubits)",
      "qubits": 50
    },
    {
      "id": "ghz_100q",
      "type": "GHZ_SCALING",
      "description": "GHZ state (100 qubits)",
      "qubits": 100
    },
    {
      "id": "depth_stress",
      "type": "DEPTH_STRESS",
      "description": "Deep circuit stress test",
      "qubits": 10
    }
  ]
}

---

Run Benchmark

Queue a benchmark run against a backend.

POST /api/v2/bench/run

Request Body:

{
  "backend_id": "ibm_brisbane",
  "workloads": ["ghz_5q", "ghz_10q", "bell_state"],
  "shots": 1024,
  "seed": 42
}

Field	Type	Required	Description
backend_id	string	Yes	Target backend ID
workloads	array	No	Workload IDs (default: ["ghz_5q", "ghz_10q", "bell_state"])
shots	integer	No	Number of shots (default: 1024, max: 100000)
seed	integer	No	Random seed for reproducibility

Response (202 Accepted):

{
  "benchmark_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "estimated_time_seconds": 90.0,
  "message": "Benchmark a1b2c3d4-e5f6-7890-abcd-ef1234567890 queued for execution on ibm_brisbane",
  "warning": null
}

Development Mode

In development mode, a warning will be returned:

{
  "warning": "DEV MODE: Using SimulatorExecutor. Results are simulated. Data stored in-memory only."
}

---

Get Benchmark Report

Retrieve the report for a completed benchmark.

GET /api/v2/bench/report/{benchmark_id}

Response:

{
  "report": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-01-12T10:30:00Z",
    "backend_id": "ibm_brisbane",
    "workloads": [
      {
        "id": "ghz_5q",
        "type": "GHZ_SCALING",
        "qubits": 5,
        "fidelity": 0.9542,
        "execution_time_ms": 245,
        "gate_count": 5,
        "depth": 5
      },
      {
        "id": "ghz_10q",
        "type": "GHZ_SCALING",
        "qubits": 10,
        "fidelity": 0.9128,
        "execution_time_ms": 389,
        "gate_count": 10,
        "depth": 10
      }
    ],
    "summary": {
      "total_workloads": 2,
      "average_fidelity": 0.9335,
      "total_execution_time_ms": 634
    }
  },
  "download_url": "/api/v2/bench/report/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download",
  "storage_mode": "ledger"
}

---

Download Benchmark Report

Download the benchmark report as a JSON file.

GET /api/v2/bench/report/{benchmark_id}/download

Response Headers:

Content-Type: application/json
Content-Disposition: attachment; filename=bench-report-a1b2c3d4.json

---

Verify Benchmark Report

Verify the integrity of a benchmark report (hashes and signature).

POST /api/v2/bench/verify

Request Body:

{
  "report": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "...": "full report JSON"
  }
}

Response:

{
  "status": "valid",
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content_hash_valid": true,
  "evidence_hash_valid": true,
  "signature_present": true,
  "signature_valid": true,
  "warnings": [],
  "error": null
}

---

Evidence Bundles (Bench V3)

The Bench V3 API provides enhanced evidence bundling with cryptographic verification.

Base URL

https://api.softqcos.softquantus.com/bench

Evidence Bundle Structure

{
  "bundle_id": "uuid-v4",
  "job_id": "job_identifier",
  "tenant_id": "tenant_identifier",
  "created_at": "2026-01-12T10:30:00Z",
  "items": [
    {
      "type": "circuit_submission",
      "content": { "...": "circuit data" },
      "hash": "sha256_hash_of_content"
    },
    {
      "type": "execution_result",
      "content": { "...": "result data" },
      "hash": "sha256_hash_of_content"
    }
  ],
  "merkle_root": "root_hash_of_all_items",
  "signatures": [
    {
      "key_id": "softquantus-2026",
      "algorithm": "ECDSA-P384",
      "signature": "base64_encoded_signature"
    }
  ]
}

---

Use Cases

Pre-Production Validation

Before running production workloads on a new quantum backend:

import requests

# Run benchmark
response = requests.post(
    "https://api.softqcos.softquantus.com/api/v2/bench/run",
    headers={"X-API-Key": "your-api-key"},
    json={
        "backend_id": "ibm_heron",
        "workloads": ["ghz_10q", "ghz_50q"],
        "shots": 4096
    }
)

benchmark_id = response.json()["benchmark_id"]
print(f"Benchmark started: {benchmark_id}")

Provider Comparison

Compare performance across providers:

backends = ["ibm_brisbane", "ionq_aria", "rigetti_ankaa"]
results = {}

for backend in backends:
    response = requests.post(
        "https://api.softqcos.softquantus.com/api/v2/bench/run",
        headers={"X-API-Key": "your-api-key"},
        json={
            "backend_id": backend,
            "workloads": ["ghz_5q", "ghz_10q"],
            "shots": 4096
        }
    )
    results[backend] = response.json()["benchmark_id"]

Compliance Evidence

Generate verifiable evidence for regulatory compliance:

# Run benchmark with seed for reproducibility
response = requests.post(
    "https://api.softqcos.softquantus.com/api/v2/bench/run",
    headers={"X-API-Key": "your-api-key"},
    json={
        "backend_id": "quantinuum_h2",
        "workloads": ["bell_state", "ghz_5q"],
        "shots": 10000,
        "seed": 12345
    }
)

# Download evidence bundle
benchmark_id = response.json()["benchmark_id"]
report = requests.get(
    f"https://api.softqcos.softquantus.com/api/v2/bench/report/{benchmark_id}",
    headers={"X-API-Key": "your-api-key"}
)

# Save for audit trail
with open(f"evidence_{benchmark_id}.json", "w") as f:
    json.dump(report.json(), f, indent=2)

---

SDK Integration

Use the SDK for simplified benchmarking:

from softqcos_sdk import QCOSClient

client = QCOSClient()

# Run benchmark
benchmark = client.bench.run(
    backend="ibm_brisbane",
    workloads=["ghz_5q", "ghz_10q"],
    shots=4096
)

# Wait for completion
report = benchmark.wait()

# Access results
for workload in report.workloads:
    print(f"{workload.id}: fidelity={workload.fidelity:.3f}")

---

Errors

Code	HTTP Status	Description
BENCHMARK_NOT_FOUND	404	Benchmark ID not found
BENCHMARK_STILL_RUNNING	202	Benchmark not yet complete
INVALID_WORKLOAD	400	Unknown workload ID
BACKEND_UNAVAILABLE	503	Target backend offline
VERIFICATION_FAILED	400	Report integrity check failed

---

See Also

• CLI verify command - Offline verification
• Optimization - Optimization benchmarking
• API Reference - Core API documentation