--- title: "POST /model/{modelId}/count-tokens" method: POST path: "/model/{modelId}/count-tokens" --- # POST /model/{modelId}/count-tokens `POST /model/{modelId}/count-tokens` Returns the token count for a given inference request. This operation helps you estimate token usage before sending requests to foundation models by returning the token count that would be used if the same input were sent to the model in an inference request. Token counting is model-specific because different models use different tokenization strategies. The token count returned by this operation will match the token count that would be charged if the same input were sent to the model in an `InvokeModel` or `Converse` request. You can use this operation to: * Estimate costs before sending inference requests. * Optimize prompts to fit within token limits. * Plan for token usage in your applications. This operation accepts the same input formats as `InvokeModel` and `Converse`, allowing you to count tokens for both raw text inputs and structured conversation formats. The following operations are related to `CountTokens`: * [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/API/API_runtime_InvokeModel.html) - Sends inference requests to foundation models * [Converse](https://docs.aws.amazon.com/bedrock/latest/API/API_runtime_Converse.html) - Sends conversation-based inference requests to foundation models ## Path parameters - `modelId` string, required — ARN or ID of a Bedrock model ## Request body - object - `input` object, required — The input value for token counting. The value should be either an InvokeModel or Converse request body. - `invokeModel` object — An InvokeModel request for which to count tokens. Use this field when you want to count tokens for a raw text input that would be sent to the InvokeModel operation. - `body` string, password, required — The request body to count tokens for, formatted according to the model's expected input format. To learn about the input format for different models, see Model inference parameters and responses. - `converse` object — A Converse request for which to count tokens. Use this field when you want to count tokens for a conversation-based input that would be sent to the Converse operation. - `messages` Message[] — An array of messages to count tokens for. - `role` 'user' | 'assistant' | 'system', required — The role that the message plays in the message. - `content` ContentBlock[], required —

The message content. Note the following restrictions:

- `text` string — Text to include in the message. - `image` object —

Image to include in the message.

This field is only supported by Anthropic Claude 3 models.

 - `format` 'png' | 'jpeg' | 'gif' | 'webp', required — The format of the image. - `source` object, required — The source for the image. - … - `error` object — Error information if the image block could not be processed or contains invalid data. - … - `document` object — A document to include in the message. - `format` 'pdf' | 'csv' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'html' | 'txt' | 'md' — The format of a document, or its extension. - `name` string, required —

A name for the document. The name can only contain the following characters:

This field is vulnerable to prompt injections, because the model might inadvertently interpret it as instructions. Therefore, we recommend that you specify a neutral name.

 - `source` object, required — Contains the content of the document. - … - `context` string — Contextual information about how the document should be processed or interpreted by the model when generating citations. - `citations` object — Configuration settings that control how citations should be generated for this specific document. - … - `video` object — Video to include in the message. - `format` 'mkv' | 'mov' | 'mp4' | 'webm' | 'flv' | 'mpeg' | 'mpg' | 'wmv' | 'three_gp', required — The block's format. - `source` object, required — The block's source. - … - `audio` object — An audio content block containing audio data in the conversation. - `format` 'mp3' | 'opus' | 'wav' | 'aac' | 'flac' | 'mp4' | 'ogg' | 'mkv' | 'mka' | 'x-aac' | 'm4a' | 'mpeg' | 'mpga' | 'pcm' | 'webm', required — The format of the audio data, such as MP3, WAV, FLAC, or other supported audio formats. - `source` object, required — The source of the audio data, which can be provided as raw bytes or an S3 location. - … - `error` object — Error information if the audio block could not be processed or contains invalid data. - … - `toolUse` object — Information about a tool use request from a model. - `toolUseId` string, required — The ID for the tool request. - `name` string, required — The name of the tool that the model wants to use. - `input` object, required — The input to pass to the tool. - `type` 'server_tool_use' — The type for the tool request. - `toolResult` object — The result for a tool request that a model makes. - `toolUseId` string, required — The ID of the tool request that this is the result for. - `content` ToolResultContentBlock[], required — The content for tool result content block. - … - `status` 'success' | 'error' —

The status for the tool result content block.

This field is only supported by Amazon Nova and Anthropic Claude 3 and 4 models.

 - `type` string — The type for the tool result content block. - `guardContent` object —

Contains the content to assess with the guardrail. If you don't specify guardContent in a call to the Converse API, the guardrail (if passed in the Converse API) assesses the entire message.

For more information, see Use a guardrail with the Converse API in the Amazon Bedrock User Guide.

- `text` object — The text to guard. - … - `image` object — Image within converse content block to be evaluated by the guardrail. - … - `cachePoint` object — CachePoint to include in the message. - `type` 'default', required — Specifies the type of cache point within the CachePointBlock. - `ttl` '5m' | '1h' — Optional TTL duration for cache entries. When specified, enables extended TTL caching with the specified duration. When omitted, uses type value for caching behavior. - `reasoningContent` object — Contains content regarding the reasoning that is carried out by the model. Reasoning refers to a Chain of Thought (CoT) that the model generates to enhance the accuracy of its final response. - `reasoningText` object — The reasoning that the model used to return the output. - … - `redactedContent` string — The content in the reasoning that was encrypted by the model provider for safety reasons. The encryption doesn't affect the quality of responses. - `citationsContent` object — A content block that contains both generated text and associated citation information, providing traceability between the response and source documents. - `content` CitationGeneratedContent[] — The generated content that is supported by the associated citations. - … - `citations` Citation[] — An array of citations that reference the source documents used to generate the associated content. - … - `searchResult` object — Search result to include in the message. - `source` string, required — The source URL or identifier for the content. - `title` string, required — A descriptive title for the search result. - `content` SearchResultContentBlock[], required — An array of search result content block. - … - `citations` object — Configuration setting for citations - … - `system` SystemContentBlock[] — The system content blocks to count tokens for. System content provides instructions or context to the model about how it should behave or respond. The token count will include any system content provided. - `text` string — A system prompt for the model. - `guardContent` object —

A content block to assess with the guardrail. Use with the Converse or ConverseStream API operations.

For more information, see Use a guardrail with the Converse API in the Amazon Bedrock User Guide.

- `text` object — The text to guard. - `text` string, required — The text that you want to guard. - `qualifiers` GuardrailConverseContentQualifier[] — The qualifier details for the guardrails contextual grounding filter. - `image` object — Image within converse content block to be evaluated by the guardrail. - `format` 'png' | 'jpeg', required — The format details for the image type of the guardrail converse image block. - `source` object, required — The image source (image bytes) of the guardrail converse image block. - … - `cachePoint` object — CachePoint to include in the system prompt. - `type` 'default', required — Specifies the type of cache point within the CachePointBlock. - `ttl` '5m' | '1h' — Optional TTL duration for cache entries. When specified, enables extended TTL caching with the specified duration. When omitted, uses type value for caching behavior. - `toolConfig` object — The toolConfig of Converse input request to count tokens for. Configuration information for the tools that the model can use when generating a response. - `tools` Tool[], required — An array of tools that you want to pass to a model. - `toolSpec` object — The specfication for the tool. - `name` string, required — The name for the tool. - `description` string — The description for the tool. - `inputSchema` object, required — The input schema for the tool in JSON format. - … - `strict` boolean — Flag to enable structured output enforcement on a tool usage response. - `systemTool` object — Specifies the system-defined tool that you want use. - `name` string, required — The name of the system-defined tool that you want to call. - `cachePoint` object — CachePoint to include in the tool configuration. - `type` 'default', required — Specifies the type of cache point within the CachePointBlock. - `ttl` '5m' | '1h' — Optional TTL duration for cache entries. When specified, enables extended TTL caching with the specified duration. When omitted, uses type value for caching behavior. - `toolChoice` object — If supported by model, forces the model to request a tool. - `auto` object — (Default). The Model automatically decides if a tool should be called or whether to generate text instead. - `any` object — The model must request at least one tool (no text is generated). - `tool` object — The Model must request the specified tool. Only supported by Anthropic Claude 3 and Amazon Nova models. - `name` string, required — The name of the tool that the model must request. - `additionalModelRequestFields` object — The additionalModelRequestFields of Converse input request to count tokens for. Use this field when you want to pass additional parameters that the model supports. ## Response `200` Success - CountTokensResponse - `inputTokens` integer, required — The number of tokens in the provided input according to the specified model's tokenization rules. This count represents the number of input tokens that would be processed if the same input were sent to the model in an inference request. Use this value to estimate costs and ensure your inputs stay within model token limits. ## Other responses - `480` — AccessDeniedException - `481` — ResourceNotFoundException - `482` — ThrottlingException - `483` — InternalServerException - `484` — ServiceUnavailableException - `485` — ValidationException --- [API](https://skmtc.net/aws/apis/bedrock-runtime.md) · [All operations](https://skmtc.net/aws/apis/bedrock-runtime/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/bedrock-runtime/versions/8a393198b636/schema)