Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Per-request metadata tagging

Request metadata lets you attach key-value tags to individual Amazon Bedrock inference calls on the bedrock-runtime endpoint. The tags are recorded with the request in your model invocation logs. You can then attribute usage to a team, application, environment, experiment, or any other dimension that varies per call. There is no resource to create or configure ahead of time — each call can carry a different set of tags.

Request metadata is supported on the following bedrock-runtime APIs:

How request metadata works

You attach metadata to a request differently depending on which API you call:

Request metadata is recorded in your model invocation logs only when logging is enabled in the AWS Region where the call is made. For setup instructions, see Monitor model invocation using CloudWatch Logs and Amazon S3.

The following example shows an InvokeModel request that tags the call with a team name, an environment, and a test case identifier:

POST /model/anthropic.claude-3-haiku-20240307-v1:0/invoke HTTP/1.1
Content-Type: application/json
X-Amzn-Bedrock-Request-Metadata: {"team": "orchestrator", "environment": "preview-test", "test_case": "invoke_model_sync"}

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 50,
  "messages": [{"role": "user", "content": "Say hello in one word."}]
}

The same header is supported on InvokeModelWithResponseStream:

POST /model/anthropic.claude-3-haiku-20240307-v1:0/invoke-with-response-stream HTTP/1.1
Content-Type: application/json
X-Amzn-Bedrock-Request-Metadata: {"team": "orchestrator", "environment": "preview-test", "test_case": "invoke_model_stream"}

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 50,
  "messages": [{"role": "user", "content": "Say hello in one word."}]
}

The following example sets request metadata with the AWS SDK for Python (Boto3) on a Converse call. The SDK includes the metadata in the SigV4-signed headers for you.

import boto3

client = boto3.client("bedrock-runtime")

response = client.converse(
    modelId="us.anthropic.claude-opus-4-8",  # or an inference profile ARN
    messages=[{"role": "user", "content": [{"text": "Summarize this ticket."}]}],
    requestMetadata={
        "user": "alice@example.com",
        "team": "growth",
        "feature": "summarizer",
        "environment": "prod",
    },
)

Limits

Request metadata has the following limits, which apply to both the X-Amzn-Bedrock-Request-Metadata header (InvokeModel, InvokeModelWithResponseStream) and the requestMetadata body field (Converse, ConverseStream):

Requests that exceed these limits are rejected with a validation error.

Where request metadata appears

Request metadata appears in your Amazon Bedrock model invocation logs under the top-level requestMetadata field. The following abbreviated log entry shows the field for an InvokeModel call:

{
    "schemaType": "ModelInvocationLog",
    "schemaVersion": "1.0",
    "timestamp": "2024-01-15T12:00:00Z",
    "accountId": "123456789012",
    "region": "us-east-1",
    "requestId": "abcd1234-5678-efgh-ijkl-mnopqrstuvwx",
    "operation": "InvokeModel",
    "modelId": "anthropic.claude-3-haiku-20240307-v1:0",
    "requestMetadata": {
        "team": "orchestrator",
        "environment": "preview-test",
        "test_case": "invoke_model_sync"
    },
    "input":  { "...": "..." },
    "output": { "...": "..." }
}

You can filter and aggregate logs by metadata fields in Amazon CloudWatch Logs Insights, Amazon S3 query tools such as Amazon Athena, or any other system that reads invocation logs.

Getting cost from your logs

Request metadata and token counts are written to your model invocation logs, not to your bill. There are two ways to turn them into cost.

Considerations