Anthropic Models

POST /v1/messages

Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. The Messages API can be used for either single queries or stateless multi-turn conversations.

Parameters

Request Body

Parameter	Type	Required	Default	Description
max_tokens	int	Yes	-	Maximum number of tokens to generate (including thinking and response content), the hard limit for total output. Models may stop before reaching this value. Set to 0 to pre-warm the prompt cache without generating a response. Different models have different maximum values. This parameter is required for Anthropic (can be omitted with this platform's API Key; the platform fills in a default value, but you can also set it freely)
messages	array	Yes	-	Input messages, each with a role (user/assistant) and content. Consecutive same-role messages are combined into a single turn; if the final message is assistant, the response continues from it (prefill)
model	string	Yes	-	The model that will complete your prompt
cache_control	object	No	-	Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request
container	object or string	No	-	Container identifier for reuse across requests (code execution tool)
context_management	object	No	-	Context management configuration, controls how the model manages context across requests (e.g. whether to clear tool results)
diagnostics	object	No	-	Request-level diagnostics, currently carries the previous response id for prompt-cache divergence reporting
fallback_credit_token	string or object	No	-	The token from a prior refusal's stop_details. Pass it when retrying a refused request to have the prefix's cache-creation tokens billed at the cache-read rate. Requires the same organization and workspace, same request body, an eligible fallback model, the same platform, and redemption within 5 minutes of the refusal
fallbacks	array or "default"	No	-	Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order. The string "default" requests the model's server-defined default fallback configuration
inference_geo	string	No	-	Specifies the geographic region for inference processing; defaults to the workspace's default_inference_geo
mcp_servers	array	No	-	MCP servers (URL definitions) to be utilized in this request, max 20
metadata	object	No	-	Request metadata, can include a user_id field to identify the end-user (for abuse monitoring and tracking), e.g. {"user_id": "user-123"}
output_config	object	No	-	Configuration options for the model's output, such as the output format
output_format	object	No	-	Deprecated: Use output_config.format instead. A schema to specify the output format in responses; will be removed in a future release
service_tier	string	No	auto	Service tier: auto (use priority capacity if available) / standard_only (standard capacity only)
speed	string	No	-	Inference speed mode: standard / fast. fast provides significantly faster output token generation at premium pricing; not all models support it, invalid combinations are rejected at create time
stop_sequences	array	No	-	Custom stop sequences. Generation stops immediately when any sequence is generated; stop_reason becomes stop_sequence and the response stop_sequence field contains the matched sequence
stream	bool	No	false	Whether to enable SSE streaming output, see Streaming Response
system	string or array	No	-	System prompt for setting the assistant's behavior, role, context, and constraints. Can be a string or an array of text blocks (for more complex instructions), effective throughout the conversation
thinking	object	No	-	Extended thinking configuration for enabling reasoning capabilities (requires model support), see Thinking Parameters
tool_choice	object	No	auto	Controls tool use, see tool_choice Parameters
tools	array	No	-	Tool definitions, see tools Fields and Tool Use Example
temperature	float	No	1.0	Deprecated: Models released after Opus 4.6 do not support setting temperature. Only 1.0 is accepted for backwards compatibility; other values return 400
top_k	int	No	-	Deprecated: Models released after Opus 4.6 do not accept top_k; any value returns 400
top_p	float	No	-	Deprecated: Models released after Opus 4.6 do not support top_p. Only values >= 0.99 are accepted for backwards compatibility; other values return 400

Request Headers

Parameter	Type	Required	Description
beta	array	No	Optional header to specify the beta version(s) you want to use
user_profile_id	string	No	The user profile ID to attribute this request to (when acting on behalf of a party other than your organization). Requires the user-profiles beta header
workspace_id	string	No	Selects the Workspace for this request (e.g. wrkspc_011CZkZaBF1tNoB5wlCeusgy). Only needed for credentials that can act on more than one Workspace; a credential belonging to a specific Workspace may omit it, and if sent it must match that Workspace

Thinking Parameters

Parameter	Type	Required	Description
type	string	Yes	adaptive (recommended, the model decides when and how deeply to think) / enabled (specify a thinking budget, supported by older models, deprecated) / disabled (disable thinking)
budget_tokens	int	No	Thinking token budget when type is enabled, minimum 1024, counts towards max_tokens

Differences in thinking configuration across models:

• cl-op-4.7 and higher (including cl-op-4.8), cl-so-5, and other newer models: only support adaptive thinking "thinking": {"type": "adaptive"}. Using the old "type": "enabled", "budget_tokens": N format returns a 400 error.
• cl-op-4.6 / cl-so-4.6 and other older models: can still use "thinking": {"type": "enabled", "budget_tokens": N} (where budget_tokens must be less than max_tokens), but this format is deprecated. It's recommended to switch to adaptive thinking.

tool_choice Parameters

type Value	Fields	Description
auto	-	The model decides whether to use tools (default)
any	-	Must use at least one tool
tool	name	Force use of a specific tool; name is the tool name
none	-	Do not use any tools

tools Fields

Field	Type	Required	Description
name	string	Yes	Name of the tool
description	string	No	Optional but strongly recommended description of the tool
input_schema	object	Yes	JSON Schema for the tool input shape that the model will produce in tool_use output content blocks

Tool Use Example

After defining tools in the request, the model may return tool_use content blocks representing tool invocations. After you run the tool, return the result to the model as a tool_result content block to continue the conversation.

curl --location --request POST 'https://neolink.com/api/v1/messages' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "max_tokens": 1024,
         "tools": [
             {
                 "name": "get_stock_price",
                 "description": "Get the current stock price for a given ticker symbol.",
                 "input_schema": {
                     "type": "object",
                     "properties": {
                         "ticker": {
                             "type": "string",
                             "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
                         }
                     },
                     "required": ["ticker"]
                 }
             }
         ],
         "messages": [
             {"role": "user", "content": "What is the S&P 500 at today?"}
         ]
     }'

The model returns a tool_use content block (with stop_reason set to tool_use):

[
    {
        "type": "tool_use",
        "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
        "name": "get_stock_price",
        "input": { "ticker": "^GSPC" }
    }
]

After running the tool, return the result in a subsequent user message as a tool_result content block:

curl --location --request POST 'https://neolink.com/api/v1/messages' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "max_tokens": 1024,
         "tools": [
             {
                 "name": "get_stock_price",
                 "description": "Get the current stock price for a given ticker symbol.",
                 "input_schema": {
                     "type": "object",
                     "properties": {
                         "ticker": {"type": "string"}
                     },
                     "required": ["ticker"]
                 }
             }
         ],
         "messages": [
             {"role": "user", "content": "What is the S&P 500 at today?"},
             {"role": "assistant", "content": [
                 {"type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": {"ticker": "^GSPC"}}
             ]},
             {"role": "user", "content": [
                 {"type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD"}
             ]}
         ]
     }'

Request Example

cURL

curl --location --request POST 'https://neolink.com/api/v1/messages' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "max_tokens": 1024,
         "messages": [
             {
                 "role": "user",
                 "content": "hello"
             }
         ]
     }'

Python

import requests

url = "https://neolink.com/api/v1/messages"

headers = {
    "Authorization": "Bearer <API Key>",
    "Content-Type": "application/json",
}

payload = {
    "model": "<Model ID>",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "hello"
        }
    ]
}

resp = requests.post(url, headers=headers, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()

reply = "".join(
    item["text"]
    for item in data.get("content", [])
    if item.get("type") == "text"
)

print("Assistant reply:")
print(reply)

Multi-turn

curl --location --request POST 'https://neolink.com/api/v1/messages' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "max_tokens": 1024,
         "messages": [
             {"role": "user", "content": "Hello, introduce yourself in one sentence."},
             {"role": "assistant", "content": "Hi, I am an AI assistant."},
             {"role": "user", "content": "Can you be more specific?"}
         ]
     }'

System Prompt

curl --location --request POST 'https://neolink.com/api/v1/messages' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "max_tokens": 1024,
         "system": "You are a professional translator. Translate user input into English.",
         "messages": [
             {"role": "user", "content": "The weather is really nice today."}
         ]
     }'

Assistant Prefill

curl --location --request POST 'https://neolink.com/api/v1/messages' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "max_tokens": 1024,
         "messages": [
             {"role": "user", "content": "What is the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
             {"role": "assistant", "content": "The best answer is ("}
         ]
     }'

Notes:

• Models are trained to operate on alternating user / assistant turns; consecutive same-role messages are combined into a single turn.
• If the final message uses the assistant role, the response content continues immediately from that message (assistant prefill), which can constrain part of the output.
• Each message's content can be a string or an array of content blocks; a string is shorthand for a single text block: {"type": "text", "text": "..."}.
• There is no system role in the Messages API; pass the system prompt via the top-level system parameter.
• A single request is limited to 100,000 messages.

Returns

Response Body

Parameter	Type	Description
type	string	Object type, always message
id	string	Unique message identifier
container	object	Information about the container used in the request (code execution tool), see container Parameters
content	array	Array of content blocks generated by the model, see Content Block Types
context_management	object	Information about context management strategies applied during the request, see context_management Parameters
diagnostics	object	Response envelope for request-level diagnostics, see diagnostics Parameters; returned only when diagnostics was supplied on the request
model	string	The model that completed this request
role	string	Conversational role, always assistant
stop_details	object	Structured information about a refusal, see stop_details
stop_reason	string	The reason we stopped, see stop_reason Values
stop_sequence	string	Which custom stop sequence was generated, null if none
usage	object	Usage statistics, see usage Fields
input_transformations	array	Changes the API made to the request's input before showing it to the model, see input_transformations Parameters; requires the thinking-binding-controls-2026-08-01 beta

container Parameters

Parameter	Type	Description
id	string	Identifier for the container used in this request
expires_at	string	The time at which the container will expire, format: date-time
skills	array	Skills loaded in the container
skills[].type	string	Type of skill: anthropic (built-in) / custom (user-defined)
skills[].skill_id	string	Skill ID, length 1~64
skills[].version	string	The resolved version: a skill version ID for custom skills, length 1~64

Content Block Types

type	Description
text	Text content, see text Block Fields
thinking	Thinking process, see thinking Block Fields
redacted_thinking	Safety-redacted thinking content, see redacted_thinking Block Fields
tool_use	Tool invocation request, see tool_use Block Fields
server_tool_use	Server-side tool invocation, see server_tool_use Block Fields
web_search_tool_result	Web search tool result, see web_search_tool_result Block Fields
web_fetch_tool_result	Web fetch tool result, see web_fetch_tool_result Block Fields
advisor_tool_result	Advisor tool result, see advisor_tool_result Block Fields
code_execution_tool_result	Code execution tool result, see code_execution_tool_result Block Fields
bash_code_execution_tool_result	Bash code execution tool result, see bash_code_execution_tool_result Block Fields
text_editor_code_execution_tool_result	Text editor code execution tool result, see text_editor_code_execution_tool_result Block Fields
tool_search_tool_result	Tool search result, see tool_search_tool_result Block Fields
mcp_tool_use	MCP tool invocation, see mcp_tool_use Block Fields
mcp_tool_result	MCP tool result, see mcp_tool_result Block Fields
container_upload	A file uploaded to the container, see container_upload Block Fields
compaction	Compaction block returned when autocompact is triggered, see compaction Block Fields
fallback	Marks the point in content where one model's output gives way to the next, see fallback Block Fields

text Block Fields

Parameter	Type	Description
type	string	Always text
text	string	Text content, minimum length 0
citations	array	Citations supporting the text block, see Citation Types

Citation Types

The citation type depends on the cited document type: citing a PDF results in page_location, plain text results in char_location, and content document results in content_block_location.

type	Fields	Description
char_location	cited_text, document_index, document_title, end_char_index, start_char_index, file_id	Character location citation for plain text; document_index/start_char_index minimum 0
page_location	cited_text, document_index, document_title, end_page_number, start_page_number, file_id	Page location citation for PDFs; start_page_number minimum 1
content_block_location	cited_text, document_index, document_title, end_block_index, start_block_index, file_id	Content block location citation; end_block_index is an exclusive end index, a single-block citation has end_block_index = start_block_index + 1; cited_text is not counted toward input/output tokens
web_search_result_location	cited_text, encrypted_index, title, url	Web search result citation; title max length 512
search_result_location	cited_text, end_block_index, start_block_index, search_result_index, source, title	Search result content block citation; search_result_index is the 0-based index among all search_result content blocks in the request (counted separately from document_index)

thinking Block Fields

Parameter	Type	Description
type	string	Always thinking
thinking	string	The text of Claude's thinking process for this block
signature	string	A value used to verify that this thinking block was generated by Claude when passed back to the API. Opaque field, should not be interpreted or parsed; pass back exactly as received (required when using tools with extended thinking)

redacted_thinking Block Fields

Parameter	Type	Description
type	string	Always redacted_thinking
data	string	The contents of this redacted thinking block, opaque and encrypted with no readable content. Pass back unchanged when continuing a multi-turn conversation

tool_use Block Fields

Parameter	Type	Description
type	string	Always tool_use
id	string	Tool invocation ID, pattern: ^[a-zA-Z0-9_-]+$
name	string	Tool name, minimum length 1
input	object	Tool input generated by the model
caller	object	Optional. Invocation source: direct (directly from the model) / code_execution_20250825, code_execution_20260120 (generated by a server-side tool, contains tool_id with srvtoolu_ prefix)
toolset_name	string	Optional. For a toolset member tool_use, the toolset family, length 1~64

server_tool_use Block Fields

Parameter	Type	Description
type	string	Always server_tool_use
id	string	Invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
name	string	Server tool name: advisor / web_search / web_fetch / code_execution / bash_code_execution / text_editor_code_execution / tool_search_tool_regex / tool_search_tool_bm25
input	object	Tool input
caller	object	Optional. Invocation source, same as tool_use block's caller

web_search_tool_result Block Fields

Parameter	Type	Description
type	string	Always web_search_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object or array	Error object (type is web_search_tool_result_error, error_code such as invalid_tool_input / unavailable / max_uses_exceeded / too_many_requests / query_too_long / request_too_large, etc.), or an array of results
content[].type	string	Always web_search_result
content[].url	string	Result URL
content[].title	string	Result title
content[].page_age	string	Page age
content[].encrypted_content	string	Encrypted content snapshot
caller	object	Optional. Invocation source, same as tool_use block's caller

web_fetch_tool_result Block Fields

Parameter	Type	Description
type	string	Always web_fetch_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object	Error object (type is web_fetch_tool_result_error, error_code such as invalid_tool_input / url_too_long / url_not_allowed / url_not_in_prior_context / url_not_accessible / unsupported_content_type / too_many_requests / max_uses_exceeded / unavailable / content_too_large, etc.), or the fetch result
content.type	string	Always web_fetch_result on success
content.url	string	Fetched content URL
content.retrieved_at	string	ISO 8601 timestamp when the content was retrieved
content.content	object	The fetched document: type is document, title is the document title, citations.enabled is the citation configuration, source is base64 (media_type: application/pdf) or text (media_type: text/plain)
caller	object	Optional. Invocation source, same as tool_use block's caller

advisor_tool_result Block Fields

Parameter	Type	Description
type	string	Always advisor_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object	Error object (type is advisor_tool_result_error, error_code such as max_uses_exceeded / prompt_too_long / too_many_requests / overloaded / unavailable / execution_time_exceeded / model_not_found, etc.), or a result block
content.type	string	advisor_result (contains text and stop_reason) or advisor_redacted_result (contains encrypted encrypted_content and stop_reason)
content.text	string	The advisor sub-inference's output text
content.stop_reason	string	The advisor sub-inference's stop reason (same values as the top-level message stop_reason)
content.encrypted_content	string	Opaque encrypted blob containing the advisor's output; round-trip verbatim, do not inspect or modify

code_execution_tool_result Block Fields

Parameter	Type	Description
type	string	Always code_execution_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object	Error object (type is code_execution_tool_result_error, error_code: invalid_tool_input / unavailable / too_many_requests / execution_time_exceeded), or a result block
content.type	string	code_execution_result or encrypted_code_execution_result (encrypted stdout, for PFC + web_search results)
content.content	array	Output file list, each with type (code_execution_output) and file_id
content.return_code	int	Process return code
content.stdout	string	Standard output (encrypted_stdout in the encrypted variant)
content.stderr	string	Standard error

bash_code_execution_tool_result Block Fields

Parameter	Type	Description
type	string	Always bash_code_execution_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object	Error object (type is bash_code_execution_tool_result_error, error_code such as invalid_tool_input / unavailable / too_many_requests / execution_time_exceeded / output_file_too_large, etc.), or a result block
content.type	string	Always bash_code_execution_result
content.content	array	Output file list, each with type (code_execution_output) and file_id
content.return_code	int	Process return code
content.stdout	string	Standard output
content.stderr	string	Standard error

text_editor_code_execution_tool_result Block Fields

Parameter	Type	Description
type	string	Always text_editor_code_execution_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object	Error object (type is text_editor_code_execution_tool_result_error, contains error_code such as invalid_tool_input / unavailable / too_many_requests / execution_time_exceeded / file_not_found, etc. and error_message), or one of the following four result blocks
content.type	string	text_editor_code_execution_view_result (view: content, file_type (text/image/pdf), num_lines, start_line, total_lines) / text_editor_code_execution_create_result (create: is_file_update) / text_editor_code_execution_str_replace_result (replace: lines, new_lines, new_start, old_lines, old_start)

tool_search_tool_result Block Fields

Parameter	Type	Description
type	string	Always tool_search_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^srvtoolu_[a-zA-Z0-9_]+$
content	object	Error object (type is tool_search_tool_result_error, contains error_code and error_message), or the search result block
content.type	string	Always tool_search_tool_search_result
content.tool_references	array	Matched tool references, each with type (tool_reference) and tool_name (length 1~256)

mcp_tool_use Block Fields

Parameter	Type	Description
type	string	Always mcp_tool_use
id	string	Invocation ID, pattern: ^[a-zA-Z0-9_-]+$
name	string	The name of the MCP tool
server_name	string	The name of the MCP server
input	object	Tool input

mcp_tool_result Block Fields

Parameter	Type	Description
type	string	Always mcp_tool_result
tool_use_id	string	The corresponding invocation ID, pattern: ^[a-zA-Z0-9_-]+$
content	string or array	Tool result: a string, or an array of text blocks (each with type (text), text, optional citations)
is_error	bool	Whether this is an error result

container_upload Block Fields

Parameter	Type	Description
type	string	Always container_upload
file_id	string	The uploaded file's ID

compaction Block Fields

Parameter	Type	Description
type	string	Always compaction
content	string	Summary of compacted content, or null if compaction failed (clients may round-trip with null content; the server treats them as no-ops)
encrypted_content	string	Opaque metadata from prior compaction, to be round-tripped verbatim

fallback Block Fields

Marks the point in content where one model's output gives way to the next. One block appears per hop where a preceding model actually ran and declined; whether a fallback model served the response is signalled by the presence of a fallback_message entry in usage.iterations, not this block. For streaming, the block arrives via the standard content_block_start / content_block_stop pair and carries no deltas.

Parameter	Type	Description
type	string	Always fallback
from.model	string	The model whose output ends at this point (the model that declined): echoes the top-level model string the caller sent when the declining hop is the requested model; the canonical id when it is a fallback model
to.model	string	The fallback model producing the content that follows, always the canonical id
trigger.type	string	Always refusal
trigger.category	string	The policy category that triggered the refusal: cyber (cyber harm) / bio (biological harm) / frontier_llm (competing AI model development) / reasoning_extraction (reproducing internal reasoning) / general_harms (other harmful areas)

context_management Parameters

Parameter	Type	Description
applied_edits	array	List of context management edits that were applied, see table below

applied_edits entry types:

type	Fields	Description
clear_tool_uses_20250919	cleared_input_tokens, cleared_tool_uses	Clear tool uses edit; both int, minimum 0
clear_thinking_20251015	cleared_input_tokens, cleared_thinking_turns	Clear thinking turns edit; both int, minimum 0

diagnostics Parameters

Parameter	Type	Description
cache_miss_reason	object	Explains why the prompt cache could not fully reuse the prefix from the request identified by diagnostics.previous_message_id; null means diagnosis is still pending (the response was serialized before the background comparison completed)

cache_miss_reason types:

type	Fields	Description
model_changed	cache_missed_input_tokens	The model changed, causing prefix mismatch
system_changed	cache_missed_input_tokens	The system prompt changed, causing prefix mismatch
tools_changed	cache_missed_input_tokens	The tools changed, causing prefix mismatch
messages_changed	cache_missed_input_tokens	The messages changed, causing prefix mismatch
previous_message_not_found	-	The previous message was not found
unavailable	-	Diagnosis unavailable

cache_missed_input_tokens is the approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

stop_reason Values

Value	Description
end_turn	The model reached a natural stopping point
max_tokens	We exceeded the requested max_tokens or the model's maximum
stop_sequence	One of your provided custom stop sequences was generated
tool_use	The model invoked one or more tools
pause_turn	We paused a long-running turn; you may provide the response back as-is in a subsequent request to let the model continue
compaction	Autocompact was triggered; the long context was replaced with a summary
refusal	Streaming classifiers intervened to handle potential policy violations
model_context_window_exceeded	We exceeded the model's context window

Always non-null in non-streaming mode; in streaming mode it is null in the message_start event and non-null otherwise.

stop_details

Parameter	Type	Description
type	string	Always refusal
category	string	The policy category that triggered the refusal: cyber / bio / frontier_llm / reasoning_extraction / general_harms
explanation	string	Human-readable explanation of the refusal (not guaranteed to be stable), null when no explanation is available
fallback_credit_token	string	Opaque code that refunds the cache-miss cost when retrying; pass it as fallback_credit_token on the retry request, expires 5 minutes after the refusal; the retry requires the same workspace and platform, a mismatch is a 400; null when not eligible
fallback_has_prefill_claim	bool	Whether the accompanying fallback_credit_token may be redeemed with the appended-assistant retry form (true: retry with the same body plus an appended assistant message; false: retry with the original body), only set when fallback_credit_token is present
recommended_model	string	The server's suggested retry target for this refusal (returned when a fallback attempt could not be made), null otherwise

usage Fields

Parameter	Type	Description
input_tokens	int	The number of input tokens used, minimum 0
output_tokens	int	The number of output tokens used (the authoritative total for billing), minimum 0
cache_creation_input_tokens	int	The number of input tokens used to create the cache entry, minimum 0
cache_read_input_tokens	int	The number of input tokens read from the cache, minimum 0
cache_creation	object	Breakdown of cached tokens by TTL: ephemeral_5m_input_tokens (5-minute cache) / ephemeral_1h_input_tokens (1-hour cache), both minimum 0
server_tool_use	object	The number of server tool requests: web_search_requests / web_fetch_requests, both minimum 0
service_tier	string	The tier used for this request: standard / priority / batch
speed	string	Inference speed mode: standard / fast
inference_geo	string	The geographic region where inference was performed
iterations	array	Per-iteration token usage breakdown, see iterations Parameters
output_tokens_details	object	Breakdown of output tokens: thinking_tokens (tokens generated as internal reasoning, including thinking-block delimiter tokens; computed by re-tokenizing the raw reasoning text, always ≤ output_tokens), minimum 0
fallback_credit	object	Outcome of the fallback_credit_token presented on this request, see fallback_credit Parameters

Total input tokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens.

iterations Parameters

One entry per sampling iteration, discriminated by type. message entries allow you to determine which iterations exceeded long context thresholds (>=200k tokens), calculate the context window size from the last message entry, and understand token accumulation across server-side tool use loops.

type	Fields	Description
message	input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, cache_creation, model	Model sampling iteration (such as the turns of a server-side tool use loop)
compaction	input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, cache_creation	Usage of the compaction operation itself (NOT the size of the compacted context, can be much smaller; do not derive the context window size from a compaction entry; not included in top-level usage fields). The input-token trigger defaults to 150,000 tokens
advisor_message	input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, cache_creation, model	Advisor sub-inference iteration
fallback_message	input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, cache_creation, model	The fallback-model attempt that served the response in a server-side fallback request (produced in place of a message entry; the presence of this entry signals a fallback model served the response)

fallback_credit Parameters

Parameter	Type	Description
status.type	string	redeemed (the retry is billed as if the conversation had been on the retry model all along) / not_applied (no reprice was applied, see reason)
status.reason	string	The reason when not_applied: body_mismatch / continuation_excluded / continuation_only / expired / invalid_target_model / not_enabled / reprice_unavailable / temporarily_unavailable / variant_fields_present / wrong_organization / wrong_platform / wrong_workspace
status.remove_to_redeem	array	Returned exactly when reason is variant_fields_present (never null, never an empty array): request fields to remove before retrying; a corrected re-send inside the token's five-minute window can still redeem

input_transformations Parameters

Changes the API made to the request's input before showing it to the model: one entry per change, in request order. Today the only entry type is thinking_dropped; more entry types may be added over time, ignore types you do not recognize.

Parameter	Type	Description
type	string	Always thinking_dropped: a thinking / redacted_thinking / connector_text block from the request's messages that was removed because it failed a binding check
path	string	Where the removed block was in your request, format messages.{i}.content.{j} (i indexes the messages array, j that message's content array)
reason	string	Which binding check removed the block: model_binding_mismatch (created by a model whose reasoning the requested model may not read) / prefix_binding_mismatch (the conversation before it differs from the conversation it was created in; the rest of that turn's consecutive thinking blocks are removed with it) / organization_binding_mismatch (created under a different organization) / end_user_binding_mismatch (created for a different end user, or removed by the consumer-organization binding). A block failing several checks reports one reason, in this order of precedence: organization_binding_mismatch > end_user_binding_mismatch > model_binding_mismatch > prefix_binding_mismatch

Removed blocks contribute nothing to usage.input_tokens. When streaming, the array is final in message_start; the final message_delta event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in message_start.

Response Example

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "cl-so-5",
  "content": [
    {
      "type": "text",
      "text": "Hi, I'm Claude."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 20,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Streaming Response

Set "stream": true in the request body and the response is returned progressively as an SSE event stream:

Event Type	Description
message_start	Message start, contains the initial message object (only input_tokens in usage has a value at this point)
content_block_start	Content block start, contains the initial empty content block
content_block_delta	Content block delta, delta.type can be text_delta (text) / input_json_delta (tool input) / thinking_delta (thinking) / signature_delta (signature) / citations_delta (citations)
content_block_stop	Content block stop
message_delta	Message-level delta, contains the final stop_reason and cumulative usage
message_stop	Message stop
ping	Keep-alive heartbeat

Streaming Example

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"cl-so-5","stop_reason":null,"usage":{"input_tokens":12,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi, I'm Claude."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":20}}

event: message_stop
data: {"type":"message_stop"}