Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Ensure openai reports `:cacheReadTokens` in `:usage` (#77341)

applebya9b9b7bb5967
diff --git a/src/metabase/metabot/self/openai.clj b/src/metabase/metabot/self/openai.clj
index ecf2dc58e1f..74a7ec9b971 100644
--- a/src/metabase/metabot/self/openai.clj
+++ b/src/metabase/metabot/self/openai.clj
@@ -18,6 +18,28 @@
Other types (e.g. reasoning summaries) are ignored."
#{:text :function_call})
+(defn- openai-usage->aisdk-usage
+ "Convert an OpenAI Responses API `usage` block into the AISDK `:usage` shape.
+
+ Unlike Anthropic's disjoint input buckets (see [[metabase.metabot.self.claude/claude-usage->aisdk-usage]]), OpenAI
+ reports cached tokens as a subset breakdown of the input total:
+
+ input_tokens — total input, cached portion included
+ input_tokens_details.cached_tokens — the cached subset of input_tokens
+ input_tokens_details.cache_write_tokens — should always be 0 (see below)
+ output_tokens — completion tokens
+
+ cache_write_tokens is absent from the Responses API docs, but present in live responses. We pass it through
+ as :cacheCreationTokens so a count would surface in usage tracking if OpenAI ever starts populating it.
+
+ Nested *_details maps are otherwise dropped: the result must stay flat so downstream `merge-with +` usage
+ accumulation is safe."
+ [u]
+ {:promptTokens (:input_tokens u 0)
+ :completionTokens (:output_tokens u 0)
+ :cacheCreationTokens (get-in u [:input_tokens_details :cache_write_tokens] 0)
+ :cacheReadTokens (get-in u [:input_tokens_details :cached_tokens] 0)})
+
(defn openai->aisdk-chunks-xf
"Translates OpenAI /v1/responses streaming events into AI SDK v5 protocol chunks.
@@ -119,9 +141,7 @@
;; still has valid partial output, so we record its usage rather than treating it as an error.
(contains? #{"response.completed" "response.incomplete"} t)
(rf {:type :usage
- :usage (let [u (:usage response)]
- {:promptTokens (:input_tokens u 0)
- :completionTokens (:output_tokens u 0)})
+ :usage (openai-usage->aisdk-usage (:usage response))
;; non-standard extension, not in AISDK5
:id (:id response)
:model @model-name})
diff --git a/test/metabase/metabot/self/openai_test.clj b/test/metabase/metabot/self/openai_test.clj
index 7af991f30e7..5df73148d66 100644
--- a/test/metabase/metabot/self/openai_test.clj
+++ b/test/metabase/metabot/self/openai_test.clj
@@ -33,8 +33,10 @@
(is (=? [{:type :start}
{:type :text :text string?}
{:type :usage
- :usage {:promptTokens pos-int?
- :completionTokens pos-int?}}]
+ :usage {:promptTokens pos-int?
+ :completionTokens pos-int?
+ :cacheCreationTokens nat-int?
+ :cacheReadTokens nat-int?}}]
(into [] (comp (openai/openai->aisdk-chunks-xf) (self.core/aisdk-xf)) raw-chunks))))))
(deftest ^:parallel openai-tool-calls-conv-test
@@ -50,8 +52,10 @@
{:type :tool-input :function string? :arguments map?}]
(take 2 parts)))
(is (=? {:type :usage
- :usage {:promptTokens pos-int?
- :completionTokens pos-int?}}
+ :usage {:promptTokens pos-int?
+ :completionTokens pos-int?
+ :cacheCreationTokens nat-int?
+ :cacheReadTokens nat-int?}}
(last parts)))))))
(deftest ^:parallel openai-structured-output-conv-test
@@ -69,8 +73,10 @@
(is (=? [{:type :start}
{:type :text :text string?}
{:type :usage
- :usage {:promptTokens pos-int?
- :completionTokens pos-int?}}]
+ :usage {:promptTokens pos-int?
+ :completionTokens pos-int?
+ :cacheCreationTokens nat-int?
+ :cacheReadTokens nat-int?}}]
(into [] (comp (openai/openai->aisdk-chunks-xf) (self.core/aisdk-xf)) raw-chunks))))))
(deftest ^:parallel openai-text-and-tool-calls-conv-test
@@ -88,8 +94,10 @@
{:type :text :text string?}
{:type :tool-input :function "get-time" :arguments {:tz string?}}
{:type :usage
- :usage {:promptTokens pos-int?
- :completionTokens pos-int?}}]
+ :usage {:promptTokens pos-int?
+ :completionTokens pos-int?
+ :cacheCreationTokens nat-int?
+ :cacheReadTokens nat-int?}}]
(into [] (comp (openai/openai->aisdk-chunks-xf) (self.core/aisdk-xf)) raw-chunks))))))
(deftest ^:parallel openai-reasoning-items-are-ignored-test
@@ -112,8 +120,10 @@
(is (=? [{:type :start}
{:type :text :text string?}
{:type :usage
- :usage {:promptTokens pos-int?
- :completionTokens pos-int?}}]
+ :usage {:promptTokens pos-int?
+ :completionTokens pos-int?
+ :cacheCreationTokens nat-int?
+ :cacheReadTokens nat-int?}}]
(into [] (comp (openai/openai->aisdk-chunks-xf) (self.core/aisdk-xf)) patched)))))))
(deftest ^:parallel openai-response-failed-surfaces-error-test
@@ -175,8 +185,10 @@
(is (=? [{:type :start}
{:type :text :text string?}
{:type :usage
- :usage {:promptTokens pos-int?
- :completionTokens pos-int?}}]
+ :usage {:promptTokens pos-int?
+ :completionTokens pos-int?
+ :cacheCreationTokens nat-int?
+ :cacheReadTokens nat-int?}}]
parts))
(testing "no error chunk is produced for an incomplete (partial-but-valid) response"
(is (empty? (filter #(= :error (:type %)) parts)))))))
@@ -185,27 +197,61 @@
;;; Usage normalization tests
;;; ──────────────────────────────────────────────────────────────────
-(deftest ^:parallel openai-usage-strips-nested-details-test
- (testing "nested *_details maps from reasoning models are stripped"
- (let [raw-chunks (fixture "openai-text"
- {:input [{:role :user :content "Say hello briefly, in under 10 words."}]})
- ;; Patch the last chunk to include nested usage details like reasoning models return
- patched (mapv (fn [chunk]
- (if (= (:type chunk) "response.completed")
- (assoc-in chunk [:response :usage]
- {:input_tokens 20
- :output_tokens 8
- :total_tokens 28
- :input_tokens_details {:cached_tokens 5 :audio_tokens 0}
- :output_tokens_details {:reasoning_tokens 3 :audio_tokens 0}})
- chunk))
- raw-chunks)
- parts (into [] (comp (openai/openai->aisdk-chunks-xf) (self.core/aisdk-xf)) patched)
- usage (:usage (last parts))]
- ;; no nested maps — safe for merge-with + in accumulate-usage-xf
- (is (= {:promptTokens 20
- :completionTokens 8}
- usage)))))
+(defn- usage-from-patched-fixture
+ "Run the openai-text fixture through the full pipeline with its terminal
+ `response.completed` usage replaced by `usage`, and return the final
+ AISDK `:usage` map."
+ [usage]
+ (let [raw-chunks (fixture "openai-text"
+ {:input [{:role :user :content "Say hello briefly, in under 10 words."}]})
+ patched (mapv (fn [chunk]
+ (cond-> chunk
+ (= (:type chunk) "response.completed")
+ (assoc-in [:response :usage] usage)))
+ raw-chunks)
+ parts (into [] (comp (openai/openai->aisdk-chunks-xf) (self.core/aisdk-xf)) patched)]
+ (:usage (last parts))))
+
+(deftest ^:parallel openai-usage-reports-cached-tokens-test
+ (testing "cached tokens from input_tokens_details (Responses API shape) are reported as :cacheReadTokens"
+ (is (= {:promptTokens 2006
+ :completionTokens 300
+ :cacheCreationTokens 0
+ :cacheReadTokens 1920}
+ (usage-from-patched-fixture
+ {:input_tokens 2006
+ :output_tokens 300
+ :total_tokens 2306
+ :input_tokens_details {:cached_tokens 1920 :cache_write_tokens 0}
+ :output_tokens_details {:reasoning_tokens 0}})))))
+
+(deftest ^:parallel openai-usage-zero-cached-tokens-test
+ (testing "input_token_details missing the cache keys reports zero cache tokens"
+ (is (= {:promptTokens 20
+ :completionTokens 8
+ :cacheCreationTokens 0
+ :cacheReadTokens 0}
+ (usage-from-patched-fixture
+ {:input_tokens 20
+ :output_tokens 8
+ :total_tokens 28
+ :input_tokens_details {}
+ :output_tokens_details {:reasoning_tokens 3}})))))
+
+(deftest ^:parallel openai-usage-cache-write-tokens-passthrough-test
+ (testing "a (hypothetical) non-zero cache_write_tokens is passed through as :cacheCreationTokens"
+ ;; The live API always reports cache_write_tokens 0 (automatic caching bills no writes), but if
+ ;; OpenAI ever starts populating it we want the count to flow through rather than be dropped.
+ (is (= {:promptTokens 20
+ :completionTokens 8
+ :cacheCreationTokens 7
+ :cacheReadTokens 0}
+ (usage-from-patched-fixture
+ {:input_tokens 20
+ :output_tokens 8
+ :total_tokens 28
+ :input_tokens_details {:cached_tokens 0 :cache_write_tokens 7}
+ :output_tokens_details {:reasoning_tokens 3}})))))
;;; ──────────────────────────────────────────────────────────────────
;;; parts->openai-input tests