feat(api): add usage to runs and run steps (#1090)

src/openai/types/beta/threads/run.py

@@ -17,6 +17,7 @@
     "ToolAssistantToolsCode",
     "ToolAssistantToolsRetrieval",
     "ToolAssistantToolsFunction",
+    "Usage",
 ]
 
 
@@ -61,6 +62,17 @@ class ToolAssistantToolsFunction(BaseModel):
 Tool = Union[ToolAssistantToolsCode, ToolAssistantToolsRetrieval, ToolAssistantToolsFunction]
 
 
+class Usage(BaseModel):
+    completion_tokens: int
+    """Number of completion tokens used over the course of the run."""
+
+    prompt_tokens: int
+    """Number of prompt tokens used over the course of the run."""
+
+    total_tokens: int
+    """Total number of tokens used (prompt + completion)."""
+
+
 class Run(BaseModel):
     id: str
     """The identifier, which can be referenced in API endpoints."""
@@ -152,3 +164,10 @@ class Run(BaseModel):
     [assistant](https://platform.openai.com/docs/api-reference/assistants) used for
     this run.
     """
+
+    usage: Optional[Usage] = None
+    """Usage statistics related to the run.
+
+    This value will be `null` if the run is not in a terminal state (i.e.
+    `in_progress`, `queued`, etc.).
+    """

src/openai/types/beta/threads/runs/run_step.py

@@ -8,7 +8,7 @@
 from .tool_calls_step_details import ToolCallsStepDetails
 from .message_creation_step_details import MessageCreationStepDetails
 
-__all__ = ["RunStep", "LastError", "StepDetails"]
+__all__ = ["RunStep", "LastError", "StepDetails", "Usage"]
 
 
 class LastError(BaseModel):
@@ -22,6 +22,17 @@ class LastError(BaseModel):
 StepDetails = Union[MessageCreationStepDetails, ToolCallsStepDetails]
 
 
+class Usage(BaseModel):
+    completion_tokens: int
+    """Number of completion tokens used over the course of the run step."""
+
+    prompt_tokens: int
+    """Number of prompt tokens used over the course of the run step."""
+
+    total_tokens: int
+    """Total number of tokens used (prompt + completion)."""
+
+
 class RunStep(BaseModel):
     id: str
     """The identifier of the run step, which can be referenced in API endpoints."""
@@ -91,3 +102,9 @@ class RunStep(BaseModel):
 
     type: Literal["message_creation", "tool_calls"]
     """The type of run step, which can be either `message_creation` or `tool_calls`."""
+
+    usage: Optional[Usage] = None
+    """Usage statistics related to the run step.
+
+    This value will be `null` while the run step's status is `in_progress`.
+    """