Add job usage method (#1827)

* Add job usage method

* add session/batch usage method

* Add release note

---------

Co-authored-by: ptristan3 <[email protected]>

qiskit_ibm_runtime/base_runtime_job.py

@@ -135,11 +135,23 @@ def cancel_result_streaming(self) -> None:
             return
         self._ws_client.disconnect(WebsocketClientCloseCode.CANCEL)
 
+    def usage(self) -> float:
+        """Return job usage in seconds."""
+        try:
+            metrics = self._api_client.job_metadata(self.job_id())
+            return metrics.get("usage", {}).get("quantum_seconds")
+        except RequestsApiError as err:
+            raise IBMRuntimeError(f"Failed to get job metadata: {err}") from None
+
     def metrics(self) -> Dict[str, Any]:
         """Return job metrics.
 
         Returns:
-            Job metrics, which includes timestamp information.
+            A dictionary with job metrics including but not limited to the following:
+
+            * ``timestamps``: Timestamps of when the job was created, started running, and finished.
+            * ``usage``: Details regarding job usage, the measurement of the amount of
+                time the QPU is locked for your workload.
 
         Raises:
             IBMRuntimeError: If a network error occurred.

qiskit_ibm_runtime/session.py

@@ -288,6 +288,20 @@ def status(self) -> Optional[str]:
 
         return None
 
+    def usage(self) -> Optional[float]:
+        """Return session usage in seconds.
+
+        Session usage is the time from when the first job starts until the session goes inactive,
+        is closed, or when its last job completes, whichever happens last.
+
+        Batch usage is the amount of time all jobs spend on the QPU.
+        """
+        if self._session_id and isinstance(self._service, QiskitRuntimeService):
+            response = self._service._api_client.session_details(self._session_id)
+            if response:
+                return response.get("elapsed_time")
+        return None
+
     def details(self) -> Optional[Dict[str, Any]]:
         """Return session details.
 

release-notes/unreleased/1827.feat.rst

@@ -0,0 +1,3 @@
+Added new methods ``Session.usage()``, ``Batch.usage()``, and ``Job.usage()`` that
+all return information regarding job and session usage.
+Please find more information here https://docs.quantum.ibm.com/guides/execution-modes#sessions-versus-batch-usage.