Sessions

A Session groups a run of Jobs and bounds what that run may spend. It does two things:

• Correlation. Jobs submitted with a session’s id are reported as one run. Usage and the ledger show the run as a whole rather than as individual jobs.
• Budgeting. max_credits and max_seconds bound the whole run, enforced across it. For a variational loop, a per-run bound is more useful than a per-job limit, which says little about the loop’s total cost.

A Qubitra session is not a hardware reservation

A Qubitra session does not reserve a backend, grant queue priority, hold state between iterations, or make any scheduling promise. This differs from sessions on some other platforms, such as Qiskit Runtime. Sessions are free to open and free to leave open.

Using one

from qubitra import QubitraClient

with QubitraClient() as client:
    session = client.sessions.create(name="vqe run", max_credits=50.0, max_seconds=1800)

    for parameters in optimiser:
        job = client.jobs.submit(
            backend_id="sim-statevector-26q",
            circuit=ANSATZ,
            observables=[HAMILTONIAN],
            parameter_values=[parameters],
            session_id=session.id,
        )
        client.jobs.wait(job.id)
        optimiser.tell(client.jobs.result(job.id).values)

    final = client.sessions.close(session.id)
    print(final.credits_used, "credits over", final.elapsed_seconds, "seconds")

session_id is the whole integration: every Job that carries it belongs to the run.

Budgets

Both bounds are optional. A session with neither correlates without limiting:

session = client.sessions.create(name="exploration")     # correlate only

A Job that would take the run past either bound is rejected at submit — InsufficientCreditsError for credits, InvalidRequestError for a session that has run out of time or been closed. Nothing is charged for a rejected submission; the bound is checked before execution starts.

credits_used and elapsed_seconds report what the platform has counted against those bounds so far:

live = client.sessions.get(session.id)
print(live.status, live.credits_used, "/", live.max_credits)

Closing

Closing stops further Jobs joining the session, which makes the run’s totals final.

closed = client.sessions.close(session.id)
closed.status          # SessionStatus.CLOSED
closed.ended_at        # when it closed

Jobs already running when a session closes are unaffected: they finish, and their usage counts against the run.

client.sessions.list() returns your organization’s sessions, newest first, so a run whose id you have lost is still findable.

When to use one

A single Job needs no session — per-job accounting already reports its cost. Use a session when a run spans many Jobs and you want a single cost figure for it, or when you want to put a ceiling on a loop before starting it.