docs: document usage.completion_tokens_details.reasoning_tokens

cloud/quickstart.mdx

@@ -117,14 +117,17 @@ The API will return a JSON response containing the model's completion:
   "usage": {
     "prompt_tokens": 11,
     "completion_tokens": 70,
+    "completion_tokens_details": {
+      "reasoning_tokens": 21
+    },
     "reasoning_tokens": 21,
     "total_tokens": 81
   }
 }
 ```
 
 <Note>
-  `zai-org/GLM-5.1-FP8` is a reasoning model, so the response includes a `reasoning_content` field and `reasoning_tokens` in `usage`. See [Reasoning Models](/cloud/reasoning-models) to control this behavior.
+  `zai-org/GLM-5.1-FP8` is a reasoning model, so the response includes a `reasoning_content` field and the reasoning token count in `usage.completion_tokens_details.reasoning_tokens` (the top-level `reasoning_tokens` is a deprecated alias). See [Reasoning Models](/cloud/reasoning-models) to control this behavior.
 </Note>
 All inference is performed within Trusted Execution Environments (TEEs), ensuring your data remains private and verifiable.
 

cloud/reasoning-models.mdx

@@ -14,7 +14,7 @@ Reasoning models can process information in two stages:
 1. **Thinking stage**: Internal reasoning process, returned in the `reasoning_content` field of the response message
 2. **Response stage**: The final answer, returned in the `content` field
 
-For most TEE-hosted models you can control whether the model uses reasoning by configuring the `chat_template_kwargs` parameter in your API requests. Reasoning output is billed as completion tokens and reported separately as `reasoning_tokens` in the `usage` object.
+For most TEE-hosted models you can control whether the model uses reasoning by configuring the `chat_template_kwargs` parameter in your API requests. Reasoning output is billed as completion tokens. The number of tokens spent thinking is reported in `usage.completion_tokens_details.reasoning_tokens`, the same location OpenAI uses, and is a subset of `completion_tokens`. The top-level `usage.reasoning_tokens` field is kept as a deprecated alias.
 
 <Tip>
   **Which models support reasoning?**
@@ -135,7 +135,7 @@ curl https://cloud-api.near.ai/v1/chat/completions \
   }'
 ```
 
-With `"thinking": false` the response contains no reasoning trace and `usage.reasoning_tokens` drops to 0.
+With `"thinking": false` the response contains no reasoning trace and `usage.completion_tokens_details.reasoning_tokens` drops to 0.
 
 <Warning>
   **`reasoning_effort` is not supported on Kimi**
@@ -180,14 +180,17 @@ When reasoning is active, responses contain the reasoning trace alongside the an
   "usage": {
     "prompt_tokens": 13,
     "completion_tokens": 81,
+    "completion_tokens_details": {
+      "reasoning_tokens": 73
+    },
     "reasoning_tokens": 73,
     "total_tokens": 94
   }
 }
 ```
 
 - `reasoning_content` — the model's internal thinking (streamed as `delta.reasoning_content` chunks when `stream: true`)
-- `usage.reasoning_tokens` — how many completion tokens were spent thinking
+- `usage.completion_tokens_details.reasoning_tokens` — how many of the completion tokens were spent thinking. It is present in non-streaming responses and in the final usage chunk of a stream when you set `stream_options: {"include_usage": true}`. The top-level `usage.reasoning_tokens` carries the same number and is deprecated.
 
 ---