Rate Limiter¶

Class: RateLimiterBlockV1

Source: inference.core.workflows.core_steps.flow_control.rate_limiter.v1.RateLimiterBlockV1

Enforce a minimum time interval between executions of downstream workflow steps, throttling execution frequency and preventing over-execution by ensuring connected steps run no more frequently than a specified cooldown period.

How This Block Works¶

This block limits the execution rate of workflow branches by enforcing a cooldown period between consecutive executions. The block:

Takes a cooldown period (in seconds), a depends_on reference, and next_steps as input
Tracks the timestamp of the last execution using an internal state variable
Calculates the current time:
For video processing: Uses video metadata (frame number and FPS) to compute a video-time-based timestamp when video_reference_image is provided
For other contexts: Uses system clock time (datetime.now())
Compares the time elapsed since the last execution against the cooldown_seconds threshold
If sufficient time has passed (elapsed time >= cooldown_seconds):
Updates the last execution timestamp
Continues execution to the specified next_steps blocks, allowing downstream processing
If insufficient time has passed (elapsed time < cooldown_seconds):
Terminates the current workflow branch, preventing downstream execution until the cooldown period expires
Returns flow control directives that either continue to next steps or terminate the branch

The block maintains execution state across workflow runs, tracking when downstream steps were last executed. The depends_on parameter establishes a dependency relationship, and the rate limiter monitors when the dependent step completes to determine if the cooldown period has elapsed. For video workflows, the block can use video-time-based timestamps (calculated from frame number and FPS) rather than wall-clock time, which is useful when processing video faster than real-time, ensuring throttling works correctly relative to video time rather than processing speed.

Requirements¶

Important Limitation: The rate limiter currently only works in video processing contexts. When used in workflows running behind HTTP services (Roboflow Hosted API, Dedicated Deployment, or self-hosted inference server), the rate limiting will have no effect for processing HTTP requests, as each request is independent and execution state is not maintained between requests.

Common Use Cases¶

Throttling Expensive Operations: Limit the frequency of resource-intensive downstream operations (e.g., execute data uploads every 5 seconds maximum, skip if attempted more frequently), preventing system overload and reducing costs for operations with usage-based pricing
Preventing Notification Spam: Throttle notification blocks to avoid overwhelming recipients (e.g., send email alerts at most once per minute when detections occur, skip redundant notifications), ensuring alerts remain meaningful and actionable
API Rate Limit Compliance: Enforce rate limits for external API calls or service integrations (e.g., limit webhook calls to external systems to once per second, prevent exceeding API quotas), ensuring compliance with external service rate limits
Database Write Optimization: Reduce write frequency to databases or data storage systems (e.g., log detection results every 10 seconds maximum, batch updates efficiently), minimizing database load and improving overall system performance
Video Processing Efficiency: Control processing rate in video workflows where fast-forward processing may generate many frames quickly (e.g., throttle analysis steps to process every 2 seconds of video time, maintain proper timing when processing faster than real-time), using video-time-based throttling for accurate rate limiting
Resource Management: Manage computational resources by limiting how frequently expensive model inference or processing steps execute (e.g., run expensive analysis at most once per 3 seconds, skip redundant processing), balancing processing speed with resource constraints

Connecting to Other Blocks¶

This block controls workflow execution flow and can be connected:

Between workflow steps where you want to throttle execution rate, placing the rate limiter between a source step (referenced in depends_on) and target steps (specified in next_steps) to enforce a minimum time interval between executions
Before notification blocks (e.g., Email Notification, Slack Notification, Twilio SMS Notification) to prevent notification spam by ensuring alerts are sent no more frequently than the cooldown period, maintaining alert effectiveness and avoiding overwhelming recipients
Before data storage blocks (e.g., Local File Sink, CSV Formatter, Roboflow Dataset Upload, Webhook Sink) to throttle write operations and reduce storage or network overhead, batching updates efficiently and preventing excessive write operations
Before external API integrations (e.g., Webhook Sink) to comply with external service rate limits, ensuring API calls don't exceed allowed frequencies and preventing rate limit errors
In video processing workflows where fast-forward processing generates frames rapidly, using video_reference_image to enable video-time-based throttling that works correctly even when processing video faster than real-time, maintaining proper execution timing relative to video playback time
After detection or analysis blocks (e.g., Object Detection, Classification, Line Counter) to throttle downstream processing triggered by frequent detections or events, ensuring expensive operations don't execute too frequently even when detections occur on every frame

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/rate_limiter@v1to add the block as as step in your workflow.

Properties¶

Name	Type	Description	Refs
`name`	`str`	Enter a unique identifier for this step..	❌
`cooldown_seconds`	`float`	Minimum number of seconds that must elapse between consecutive executions of the next_steps blocks. The rate limiter tracks the last execution timestamp and only allows execution to continue if at least this many seconds have passed since the previous execution. Must be greater than or equal to 0.0. For video workflows, this cooldown period is enforced based on video time (calculated from frame number and FPS) when video_reference_image is provided, rather than wall-clock time..	❌

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections¶

Compatible Blocks

Check what blocks you can connect to Rate Limiter in version v1.

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Rate Limiter in version v1 has.

Bindings

input
- depends_on (*): Reference to the workflow step that immediately precedes this rate limiter block. This establishes the dependency relationship - the rate limiter monitors when this step completes to determine if the cooldown period has elapsed since the last execution. The depends_on step can be any workflow block whose output triggers the rate-limited downstream processing..
- next_steps (step): List of workflow steps to execute if the rate limit allows (i.e., sufficient time has passed since the last execution). These steps receive control flow only when the cooldown period has elapsed, enabling throttled downstream processing. If the cooldown period hasn't elapsed, these steps will not execute as the branch terminates. Each step selector references a block in the workflow that should execute when rate limiting permits..
- video_reference_image (image): Optional reference to a video frame image to use for video-time-based timestamp generation. When provided, the rate limiter calculates timestamps based on video metadata (frame number and FPS) rather than system clock time. This is useful when processing video faster than real-time, ensuring rate limiting works correctly relative to video playback time rather than processing speed. If not provided (None), the block uses system clock time (datetime.now()). Only applicable for video processing workflows..
output

Example JSON definition of step Rate Limiter in version v1

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/rate_limiter@v1",
    "cooldown_seconds": 1.0,
    "depends_on": "$steps.model",
    "next_steps": [
        "$steps.upload"
    ],
    "video_reference_image": "$inputs.image"
}