Read server-side tool usage on Grok API responses

Agentic Responses and xAI SDK chats expose two related fields. They answer different questions, and only one drives tool invocation billing.

tool_calls — every attempt

response.tool_calls

Lists each attempted tool call: id, function.name, function.arguments. Includes failures (bad URL, deleted post, malformed args, transient errors). While streaming, read chunk.tool_calls to watch decisions live. Server-side tool outputs are not returned; the agent keeps them internal.

server_side_tool_usage — successful, billable

response.server_side_tool_usage
# e.g. {'SERVER_SIDE_TOOL_X_SEARCH': 3, 'SERVER_SIDE_TOOL_WEB_SEARCH': 2}

Map of successfully executed tools → invocation counts. Failed attempts do not appear here and are not charged as tool invocations.

In the xAI SDK, tool_calls names are specific (web_search, browse_page, x_keyword_search, …) while server_side_tool_usage keys are category buckets (SERVER_SIDE_TOOL_WEB_SEARCH, SERVER_SIDE_TOOL_X_SEARCH, …). On the Responses API, web search activity also shows up as web_search_call output items.

Token fields on the same response

Field	Meaning
completion_tokens	Final text only (often small)
prompt_tokens	Cumulative prompt across agent steps
reasoning_tokens	Internal planning / analysis
cached_prompt_text_tokens	Prompt served from cache
prompt_image_tokens	Vision tokens if images/videos were processed

Prompt totals grow across turns; cache hits usually rise with them. Dollar amount for the call still lands in usage.cost_in_usd_ticks — see Read API request cost in USD ticks.

Client-side vs server-side

With the xAI SDK, get_tool_call_type(tool_call) returns values such as "client_side_tool" (you must run it locally) vs "web_search_tool", "x_search_tool", "code_execution_tool", "collections_search_tool", "mcp_tool" (server-handled). On Responses, check response.output[].type (function_call vs web_search_call / x_search_call / code_interpreter_call / file_search_call / mcp_call).

Pitfalls

• Estimating spend from len(tool_calls) — failed attempts inflate that list without matching server_side_tool_usage.
• Expecting tool outputs in the API payload for server-side tools — only the final answer and citations/usage are returned.