From 1808ebec35197faa03d5a44304a79c909483e77a Mon Sep 17 00:00:00 2001
From: kevin-tian <kevin.tian@ibm.com>
Date: Mon, 29 Jul 2024 20:06:07 -0400
Subject: [PATCH 1/3] Add job usage method

---
 qiskit_ibm_runtime/base_runtime_job.py | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/qiskit_ibm_runtime/base_runtime_job.py b/qiskit_ibm_runtime/base_runtime_job.py
index 2964407fa..675ae04e1 100644
--- a/qiskit_ibm_runtime/base_runtime_job.py
+++ b/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) -> Dict[str, Any]:
+        """Return job usage in seconds."""
+        try:
+            metrics = self._api_client.job_metadata(self.job_id())
+            return metrics.get("usage")
+        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``: Job usage metrics
+
 
         Raises:
             IBMRuntimeError: If a network error occurred.

From ac96aebd0bd600dafc016637ab94da2757ea272c Mon Sep 17 00:00:00 2001
From: kevin-tian <kevin.tian@ibm.com>
Date: Tue, 13 Aug 2024 14:15:07 -0400
Subject: [PATCH 2/3] add session/batch usage method

---
 qiskit_ibm_runtime/base_runtime_job.py |  8 ++++----
 qiskit_ibm_runtime/session.py          | 14 ++++++++++++++
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/qiskit_ibm_runtime/base_runtime_job.py b/qiskit_ibm_runtime/base_runtime_job.py
index 675ae04e1..6af93db96 100644
--- a/qiskit_ibm_runtime/base_runtime_job.py
+++ b/qiskit_ibm_runtime/base_runtime_job.py
@@ -135,11 +135,11 @@ def cancel_result_streaming(self) -> None:
             return
         self._ws_client.disconnect(WebsocketClientCloseCode.CANCEL)
 
-    def usage(self) -> Dict[str, Any]:
+    def usage(self) -> float:
         """Return job usage in seconds."""
         try:
             metrics = self._api_client.job_metadata(self.job_id())
-            return metrics.get("usage")
+            return metrics.get("usage", {}).get("quantum_seconds")
         except RequestsApiError as err:
             raise IBMRuntimeError(f"Failed to get job metadata: {err}") from None
 
@@ -150,8 +150,8 @@ def metrics(self) -> Dict[str, Any]:
             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``: Job usage metrics
-
+            * ``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.
diff --git a/qiskit_ibm_runtime/session.py b/qiskit_ibm_runtime/session.py
index d2137afc4..fc054fcbd 100644
--- a/qiskit_ibm_runtime/session.py
+++ b/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.
 

From f4d29f88a828a52751658cf42cc5156a5f19587c Mon Sep 17 00:00:00 2001
From: kevin-tian <kevin.tian@ibm.com>
Date: Tue, 13 Aug 2024 14:22:33 -0400
Subject: [PATCH 3/3] Add release note

---
 release-notes/unreleased/1827.feat.rst | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 release-notes/unreleased/1827.feat.rst

diff --git a/release-notes/unreleased/1827.feat.rst b/release-notes/unreleased/1827.feat.rst
new file mode 100644
index 000000000..c07a31b53
--- /dev/null
+++ b/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.
\ No newline at end of file