BedrockAgentCoreControl / Client / create_gateway_rate_limit

create_gateway_rate_limit

BedrockAgentCoreControl.Client.create_gateway_rate_limit(**kwargs)

Creates a rate limit for a gateway. Rate limits define throttling rules for each dimension that control request rates, token consumption rates, and concurrent connections through the gateway.

See also: AWS API Documentation

Request Syntax

response = client.create_gateway_rate_limit(
    gatewayIdentifier='string',
    clientToken='string',
    rateLimitId='string',
    description='string',
    dimensionKeys=[
        'string',
    ],
    entries=[
        {
            'dimensions': {
                'string': 'string'
            },
            'requests': [
                {
                    'rate': 123.0,
                    'period': 'second'|'minute'
                },
            ],
            'tokens': [
                {
                    'rate': 123.0,
                    'period': 'second'|'minute'
                },
            ],
            'connections': [
                {
                    'rate': 123.0,
                    'period': 'second'|'minute'
                },
            ]
        },
    ]
)
Parameters:

  • gatewayIdentifier (string) –

    [REQUIRED]

    The unique identifier of the gateway to create the rate limit for.

  • clientToken (string) –

    A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don’t specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn’t return an error. For more information, see Ensuring idempotency.

    This field is autopopulated if not provided.

  • rateLimitId (string) – An optional customer-defined identifier for the rate limit. If not provided, the system generates one.

  • description (string) – An optional human-readable description for this rate limit. If not provided, the rate limit is created without a description.

  • dimensionKeys (list) –

    [REQUIRED]

    The ordered list of dimension key names that define the scope of this rate limit. Must be unique per gateway—no two rate limits can share the same dimension keys.

    • (string) –

      A dimension key specifying the scope dimension for rate limiting.

      Allowed values: targetName, toolName, qualifiedModelId, or context-path expressions: $.context.iam.principal, $.context.iam.sourceIdentity, $.context.jwt.<claim> where <claim> is a JWT claim name (for example, $.context.jwt.sub). Validated server-side to enforce allowed prefixes and patterns.

  • entries (list) –

    [REQUIRED]

    The rule entries that map dimension values to rate configurations.

    • (dict) –

      A single rule entry within a rate limit that maps dimension values to rate configurations. Each entry defines the rate limits for a specific combination of dimension values.

      • dimensions (dict) – [REQUIRED]

        A map of dimension names to dimension values for this rule entry. Keys must match the parent rate limit’s dimension keys. Values may use * as a wildcard, but only in trailing positions based on the dimension keys ordering.

        • (string) –

          A dimension key specifying the scope dimension for rate limiting.

          Allowed values: targetName, toolName, qualifiedModelId, or context-path expressions: $.context.iam.principal, $.context.iam.sourceIdentity, $.context.jwt.<claim> where <claim> is a JWT claim name (for example, $.context.jwt.sub). Validated server-side to enforce allowed prefixes and patterns.

          • (string) –

            A dimension value in a rule entry (exact value or * wildcard).

      • requests (list) –

        The request rate limit configuration. Specifies the maximum number of requests allowed per time period.

        • (dict) –

          Contains the rate configuration for a rate limit metric, specifying the allowed rate and time period.

          • rate (float) – [REQUIRED]

            The rate value for the limit. For request limits, this is the number of requests allowed per period. For token limits, this is the number of tokens allowed per period. For connection limits, this is the number of concurrent connections allowed.

          • period (string) – [REQUIRED]

            The time period for the rate limit. Valid values:

            • second—Measures the rate limit over a one-second window.

            • minute—Measures the rate limit over a one-minute window.

      • tokens (list) –

        The token rate limit configuration. Specifies the maximum number of tokens allowed per time period.

        • (dict) –

          Contains the rate configuration for a rate limit metric, specifying the allowed rate and time period.

          • rate (float) – [REQUIRED]

            The rate value for the limit. For request limits, this is the number of requests allowed per period. For token limits, this is the number of tokens allowed per period. For connection limits, this is the number of concurrent connections allowed.

          • period (string) – [REQUIRED]

            The time period for the rate limit. Valid values:

            • second—Measures the rate limit over a one-second window.

            • minute—Measures the rate limit over a one-minute window.

      • connections (list) –

        The connection rate limit configuration. Specifies the maximum number of concurrent connections allowed.

        • (dict) –

          Contains the rate configuration for a rate limit metric, specifying the allowed rate and time period.

          • rate (float) – [REQUIRED]

            The rate value for the limit. For request limits, this is the number of requests allowed per period. For token limits, this is the number of tokens allowed per period. For connection limits, this is the number of concurrent connections allowed.

          • period (string) – [REQUIRED]

            The time period for the rate limit. Valid values:

            • second—Measures the rate limit over a one-second window.

            • minute—Measures the rate limit over a one-minute window.

Return type:

dict

Returns:

Response Syntax

{
    'rateLimitId': 'string',
    'gatewayIdentifier': 'string',
    'description': 'string',
    'dimensionKeys': [
        'string',
    ],
    'entries': [
        {
            'dimensions': {
                'string': 'string'
            },
            'requests': [
                {
                    'rate': 123.0,
                    'period': 'second'|'minute'
                },
            ],
            'tokens': [
                {
                    'rate': 123.0,
                    'period': 'second'|'minute'
                },
            ],
            'connections': [
                {
                    'rate': 123.0,
                    'period': 'second'|'minute'
                },
            ]
        },
    ],
    'status': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING',
    'createdAt': datetime(2015, 1, 1),
    'updatedAt': datetime(2015, 1, 1)
}

Response Structure

  • (dict) –

    Shared fields for GatewayRateLimit responses.

    • rateLimitId (string) –

      The unique identifier of the created rate limit.

    • gatewayIdentifier (string) –

      The unique identifier of the gateway.

    • description (string) –

      The human-readable description of the rate limit.

    • dimensionKeys (list) –

      The ordered list of dimension key names that define the scope of this rate limit.

      • (string) –

        A dimension key specifying the scope dimension for rate limiting.

        Allowed values: targetName, toolName, qualifiedModelId, or context-path expressions: $.context.iam.principal, $.context.iam.sourceIdentity, $.context.jwt.<claim> where <claim> is a JWT claim name (for example, $.context.jwt.sub). Validated server-side to enforce allowed prefixes and patterns.

    • entries (list) –

      The list of rule entries that map dimension values to rate configurations.

      • (dict) –

        A single rule entry within a rate limit that maps dimension values to rate configurations. Each entry defines the rate limits for a specific combination of dimension values.

        • dimensions (dict) –

          A map of dimension names to dimension values for this rule entry. Keys must match the parent rate limit’s dimension keys. Values may use * as a wildcard, but only in trailing positions based on the dimension keys ordering.

          • (string) –

            A dimension key specifying the scope dimension for rate limiting.

            Allowed values: targetName, toolName, qualifiedModelId, or context-path expressions: $.context.iam.principal, $.context.iam.sourceIdentity, $.context.jwt.<claim> where <claim> is a JWT claim name (for example, $.context.jwt.sub). Validated server-side to enforce allowed prefixes and patterns.

            • (string) –

              A dimension value in a rule entry (exact value or * wildcard).

        • requests (list) –

          The request rate limit configuration. Specifies the maximum number of requests allowed per time period.

          • (dict) –

            Contains the rate configuration for a rate limit metric, specifying the allowed rate and time period.

            • rate (float) –

              The rate value for the limit. For request limits, this is the number of requests allowed per period. For token limits, this is the number of tokens allowed per period. For connection limits, this is the number of concurrent connections allowed.

            • period (string) –

              The time period for the rate limit. Valid values:

              • second—Measures the rate limit over a one-second window.

              • minute—Measures the rate limit over a one-minute window.

        • tokens (list) –

          The token rate limit configuration. Specifies the maximum number of tokens allowed per time period.

          • (dict) –

            Contains the rate configuration for a rate limit metric, specifying the allowed rate and time period.

            • rate (float) –

              The rate value for the limit. For request limits, this is the number of requests allowed per period. For token limits, this is the number of tokens allowed per period. For connection limits, this is the number of concurrent connections allowed.

            • period (string) –

              The time period for the rate limit. Valid values:

              • second—Measures the rate limit over a one-second window.

              • minute—Measures the rate limit over a one-minute window.

        • connections (list) –

          The connection rate limit configuration. Specifies the maximum number of concurrent connections allowed.

          • (dict) –

            Contains the rate configuration for a rate limit metric, specifying the allowed rate and time period.

            • rate (float) –

              The rate value for the limit. For request limits, this is the number of requests allowed per period. For token limits, this is the number of tokens allowed per period. For connection limits, this is the number of concurrent connections allowed.

            • period (string) –

              The time period for the rate limit. Valid values:

              • second—Measures the rate limit over a one-second window.

              • minute—Measures the rate limit over a one-minute window.

    • status (string) –

      The current status of the rate limit.

    • createdAt (datetime) –

      The timestamp when the rate limit was created.

    • updatedAt (datetime) –

      The timestamp when the rate limit was last updated.

Exceptions