AWS CLI Command Reference

[ aws . bedrock-runtime ]

count-tokens

Description

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 - Sends inference requests to foundation models
  • Converse - Sends conversation-based inference requests to foundation models

See also: AWS API Documentation

count-tokens uses document type values. Document types follow the JSON data model where valid values are: strings, numbers, booleans, null, arrays, and objects. For command input, options and nested parameters that are labeled with the type document must be provided as JSON. Shorthand syntax does not support document types.

Synopsis

  count-tokens
--model-id <value>
--input <value>
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Options

--model-id (string)

The unique identifier or ARN of the foundation model to use for token counting. Each model processes tokens differently, so the token count is specific to the model you specify.

--input (tagged union structure)

The input for which to count tokens. The structure of this parameter depends on whether you’re counting tokens for an InvokeModel or Converse request:

  • For InvokeModel requests, provide the request body in the invokeModel field
  • For Converse requests, provide the messages and system content in the converse field

The input format must be compatible with the model specified in the modelId parameter.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: invokeModel, converse.

invokeModel -> (structure)

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 -> (blob)

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 -> (structure)

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 -> (list)

An array of messages to count tokens for.

(structure)

A message input, or returned from, a call to Converse or ConverseStream .

role -> (string)

The role that the message plays in the message.

content -> (list)

The message content. Note the following restrictions:

  • You can include up to 20 images. Each image’s size, height, and width must be no more than 3.75 MB, 8000 px, and 8000 px, respectively.
  • You can include up to five documents. Each document’s size must be no more than 4.5 MB.
  • If you include a ContentBlock with a document field in the array, you must also include a ContentBlock with a text field.
  • You can only include images and documents if the role is user .

(tagged union structure)

A block of content for a message that you pass to, or receive from, a model with the Converse or ConverseStream API operations.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text, image, document, video, toolUse, toolResult, guardContent, cachePoint, reasoningContent, citationsContent.

text -> (string)

Text to include in the message.

image -> (structure)

Image to include in the message.

Note

This field is only supported by Anthropic Claude 3 models.

format -> (string)

The format of the image.

source -> (tagged union structure)

The source for the image.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes, s3Location.

bytes -> (blob)

The raw image bytes for the image. If you use an AWS SDK, you don’t need to encode the image bytes in base64.

s3Location -> (structure)

The location of an image object in an Amazon S3 bucket. To see which models support S3 uploads, see Supported models and features for Converse .

uri -> (string)

An object URI starting with s3:// .

bucketOwner -> (string)

If the bucket belongs to another AWS account, specify that account’s ID.

document -> (structure)

A document to include in the message.

format -> (string)

The format of a document, or its extension.

name -> (string)

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

  • Alphanumeric characters
  • Whitespace characters (no more than one in a row)
  • Hyphens
  • Parentheses
  • Square brackets

Note

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 -> (tagged union structure)

Contains the content of the document.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes, s3Location, text, content.

bytes -> (blob)

The raw bytes for the document. If you use an Amazon Web Services SDK, you don’t need to encode the bytes in base64.

s3Location -> (structure)

The location of a document object in an Amazon S3 bucket. To see which models support S3 uploads, see Supported models and features for Converse .

uri -> (string)

An object URI starting with s3:// .

bucketOwner -> (string)

If the bucket belongs to another AWS account, specify that account’s ID.

text -> (string)

The text content of the document source.

content -> (list)

The structured content of the document source, which may include various content blocks such as text, images, or other document elements.

(tagged union structure)

Contains the actual content of a document that can be processed by the model and potentially cited in the response.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text.

text -> (string)

The text content of the document.

context -> (string)

Contextual information about how the document should be processed or interpreted by the model when generating citations.

citations -> (structure)

Configuration settings that control how citations should be generated for this specific document.

enabled -> (boolean)

Specifies whether document citations should be included in the model’s response. When set to true, the model can generate citations that reference the source documents used to inform the response.

video -> (structure)

Video to include in the message.

format -> (string)

The block’s format.

source -> (tagged union structure)

The block’s source.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes, s3Location.

bytes -> (blob)

Video content encoded in base64.

s3Location -> (structure)

The location of a video object in an Amazon S3 bucket. To see which models support S3 uploads, see Supported models and features for Converse .

uri -> (string)

An object URI starting with s3:// .

bucketOwner -> (string)

If the bucket belongs to another AWS account, specify that account’s ID.

toolUse -> (structure)

Information about a tool use request from a model.

toolUseId -> (string)

The ID for the tool request.

name -> (string)

The name of the tool that the model wants to use.

input -> (document)

The input to pass to the tool.

toolResult -> (structure)

The result for a tool request that a model makes.

toolUseId -> (string)

The ID of the tool request that this is the result for.

content -> (list)

The content for tool result content block.

(tagged union structure)

The tool result content block.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: json, text, image, document, video.

json -> (document)

A tool result that is JSON format data.

text -> (string)

A tool result that is text.

image -> (structure)

A tool result that is an image.

Note

This field is only supported by Anthropic Claude 3 models.

format -> (string)

The format of the image.

source -> (tagged union structure)

The source for the image.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes, s3Location.

bytes -> (blob)

The raw image bytes for the image. If you use an AWS SDK, you don’t need to encode the image bytes in base64.

s3Location -> (structure)

The location of an image object in an Amazon S3 bucket. To see which models support S3 uploads, see Supported models and features for Converse .

uri -> (string)

An object URI starting with s3:// .

bucketOwner -> (string)

If the bucket belongs to another AWS account, specify that account’s ID.

document -> (structure)

A tool result that is a document.

format -> (string)

The format of a document, or its extension.

name -> (string)

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

  • Alphanumeric characters
  • Whitespace characters (no more than one in a row)
  • Hyphens
  • Parentheses
  • Square brackets

Note

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 -> (tagged union structure)

Contains the content of the document.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes, s3Location, text, content.

bytes -> (blob)

The raw bytes for the document. If you use an Amazon Web Services SDK, you don’t need to encode the bytes in base64.

s3Location -> (structure)

The location of a document object in an Amazon S3 bucket. To see which models support S3 uploads, see Supported models and features for Converse .

uri -> (string)

An object URI starting with s3:// .

bucketOwner -> (string)

If the bucket belongs to another AWS account, specify that account’s ID.

text -> (string)

The text content of the document source.

content -> (list)

The structured content of the document source, which may include various content blocks such as text, images, or other document elements.

(tagged union structure)

Contains the actual content of a document that can be processed by the model and potentially cited in the response.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text.

text -> (string)

The text content of the document.

context -> (string)

Contextual information about how the document should be processed or interpreted by the model when generating citations.

citations -> (structure)

Configuration settings that control how citations should be generated for this specific document.

enabled -> (boolean)

Specifies whether document citations should be included in the model’s response. When set to true, the model can generate citations that reference the source documents used to inform the response.

video -> (structure)

A tool result that is video.

format -> (string)

The block’s format.

source -> (tagged union structure)

The block’s source.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes, s3Location.

bytes -> (blob)

Video content encoded in base64.

s3Location -> (structure)

The location of a video object in an Amazon S3 bucket. To see which models support S3 uploads, see Supported models and features for Converse .

uri -> (string)

An object URI starting with s3:// .

bucketOwner -> (string)

If the bucket belongs to another AWS account, specify that account’s ID.

status -> (string)

The status for the tool result content block.

Note

This field is only supported Anthropic Claude 3 models.

guardContent -> (tagged union structure)

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 .

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text, image.

text -> (structure)

The text to guard.

text -> (string)

The text that you want to guard.

qualifiers -> (list)

The qualifier details for the guardrails contextual grounding filter.

(string)

image -> (structure)

Image within converse content block to be evaluated by the guardrail.

format -> (string)

The format details for the image type of the guardrail converse image block.

source -> (tagged union structure)

The image source (image bytes) of the guardrail converse image block.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes.

bytes -> (blob)

The raw image bytes for the image.

cachePoint -> (structure)

CachePoint to include in the message.

type -> (string)

Specifies the type of cache point within the CachePointBlock.

reasoningContent -> (tagged union structure)

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.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: reasoningText, redactedContent.

reasoningText -> (structure)

The reasoning that the model used to return the output.

text -> (string)

The reasoning that the model used to return the output.

signature -> (string)

A token that verifies that the reasoning text was generated by the model. If you pass a reasoning block back to the API in a multi-turn conversation, include the text and its signature unmodified.

redactedContent -> (blob)

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 -> (structure)

A content block that contains both generated text and associated citation information, providing traceability between the response and source documents.

content -> (list)

The generated content that is supported by the associated citations.

(tagged union structure)

Contains the generated text content that corresponds to or is supported by a citation from a source document.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text.

text -> (string)

The text content that was generated by the model and is supported by the associated citation.

citations -> (list)

An array of citations that reference the source documents used to generate the associated content.

(structure)

Contains information about a citation that references a specific source document. Citations provide traceability between the model’s generated response and the source documents that informed that response.

title -> (string)

The title or identifier of the source document being cited.

sourceContent -> (list)

The specific content from the source document that was referenced or cited in the generated response.

(tagged union structure)

Contains the actual text content from a source document that is being cited or referenced in the model’s response.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text.

text -> (string)

The text content from the source document that is being cited.

location -> (tagged union structure)

The precise location within the source document where the cited content can be found, including character positions, page numbers, or chunk identifiers.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: documentChar, documentPage, documentChunk.

documentChar -> (structure)

The character-level location within the document where the cited content is found.

documentIndex -> (integer)

The index of the document within the array of documents provided in the request.

start -> (integer)

The starting character position of the cited content within the document.

end -> (integer)

The ending character position of the cited content within the document.

documentPage -> (structure)

The page-level location within the document where the cited content is found.

documentIndex -> (integer)

The index of the document within the array of documents provided in the request.

start -> (integer)

The starting page number of the cited content within the document.

end -> (integer)

The ending page number of the cited content within the document.

documentChunk -> (structure)

The chunk-level location within the document where the cited content is found, typically used for documents that have been segmented into logical chunks.

documentIndex -> (integer)

The index of the document within the array of documents provided in the request.

start -> (integer)

The starting chunk identifier or index of the cited content within the document.

end -> (integer)

The ending chunk identifier or index of the cited content within the document.

system -> (list)

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.

(tagged union structure)

A system content block.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text, guardContent, cachePoint.

text -> (string)

A system prompt for the model.

guardContent -> (tagged union structure)

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 .

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text, image.

text -> (structure)

The text to guard.

text -> (string)

The text that you want to guard.

qualifiers -> (list)

The qualifier details for the guardrails contextual grounding filter.

(string)

image -> (structure)

Image within converse content block to be evaluated by the guardrail.

format -> (string)

The format details for the image type of the guardrail converse image block.

source -> (tagged union structure)

The image source (image bytes) of the guardrail converse image block.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bytes.

bytes -> (blob)

The raw image bytes for the image.

cachePoint -> (structure)

CachePoint to include in the system prompt.

type -> (string)

Specifies the type of cache point within the CachePointBlock.

JSON Syntax:

{
  "invokeModel": {
    "body": blob
  },
  "converse": {
    "messages": [
      {
        "role": "user"|"assistant",
        "content": [
          {
            "text": "string",
            "image": {
              "format": "png"|"jpeg"|"gif"|"webp",
              "source": {
                "bytes": blob,
                "s3Location": {
                  "uri": "string",
                  "bucketOwner": "string"
                }
              }
            },
            "document": {
              "format": "pdf"|"csv"|"doc"|"docx"|"xls"|"xlsx"|"html"|"txt"|"md",
              "name": "string",
              "source": {
                "bytes": blob,
                "s3Location": {
                  "uri": "string",
                  "bucketOwner": "string"
                },
                "text": "string",
                "content": [
                  {
                    "text": "string"
                  }
                  ...
                ]
              },
              "context": "string",
              "citations": {
                "enabled": true|false
              }
            },
            "video": {
              "format": "mkv"|"mov"|"mp4"|"webm"|"flv"|"mpeg"|"mpg"|"wmv"|"three_gp",
              "source": {
                "bytes": blob,
                "s3Location": {
                  "uri": "string",
                  "bucketOwner": "string"
                }
              }
            },
            "toolUse": {
              "toolUseId": "string",
              "name": "string",
              "input": {...}
            },
            "toolResult": {
              "toolUseId": "string",
              "content": [
                {
                  "json": {...},
                  "text": "string",
                  "image": {
                    "format": "png"|"jpeg"|"gif"|"webp",
                    "source": {
                      "bytes": blob,
                      "s3Location": {
                        "uri": "string",
                        "bucketOwner": "string"
                      }
                    }
                  },
                  "document": {
                    "format": "pdf"|"csv"|"doc"|"docx"|"xls"|"xlsx"|"html"|"txt"|"md",
                    "name": "string",
                    "source": {
                      "bytes": blob,
                      "s3Location": {
                        "uri": "string",
                        "bucketOwner": "string"
                      },
                      "text": "string",
                      "content": [
                        {
                          "text": "string"
                        }
                        ...
                      ]
                    },
                    "context": "string",
                    "citations": {
                      "enabled": true|false
                    }
                  },
                  "video": {
                    "format": "mkv"|"mov"|"mp4"|"webm"|"flv"|"mpeg"|"mpg"|"wmv"|"three_gp",
                    "source": {
                      "bytes": blob,
                      "s3Location": {
                        "uri": "string",
                        "bucketOwner": "string"
                      }
                    }
                  }
                }
                ...
              ],
              "status": "success"|"error"
            },
            "guardContent": {
              "text": {
                "text": "string",
                "qualifiers": ["grounding_source"|"query"|"guard_content", ...]
              },
              "image": {
                "format": "png"|"jpeg",
                "source": {
                  "bytes": blob
                }
              }
            },
            "cachePoint": {
              "type": "default"
            },
            "reasoningContent": {
              "reasoningText": {
                "text": "string",
                "signature": "string"
              },
              "redactedContent": blob
            },
            "citationsContent": {
              "content": [
                {
                  "text": "string"
                }
                ...
              ],
              "citations": [
                {
                  "title": "string",
                  "sourceContent": [
                    {
                      "text": "string"
                    }
                    ...
                  ],
                  "location": {
                    "documentChar": {
                      "documentIndex": integer,
                      "start": integer,
                      "end": integer
                    },
                    "documentPage": {
                      "documentIndex": integer,
                      "start": integer,
                      "end": integer
                    },
                    "documentChunk": {
                      "documentIndex": integer,
                      "start": integer,
                      "end": integer
                    }
                  }
                }
                ...
              ]
            }
          }
          ...
        ]
      }
      ...
    ],
    "system": [
      {
        "text": "string",
        "guardContent": {
          "text": {
            "text": "string",
            "qualifiers": ["grounding_source"|"query"|"guard_content", ...]
          },
          "image": {
            "format": "png"|"jpeg",
            "source": {
              "bytes": blob
            }
          }
        },
        "cachePoint": {
          "type": "default"
        }
      }
      ...
    ]
  }
}

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

  • json
  • text
  • table
  • yaml
  • yaml-stream

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

  • on
  • off
  • auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb:// will always be treated as binary and use the file contents directly regardless of the cli-binary-format setting. When using file:// the file contents will need to properly formatted for the configured cli-binary-format.

  • base64
  • raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

Output

inputTokens -> (integer)

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.
© Copyright 2025, Amazon Web Services. Created using Sphinx.