Rate Limiter¶

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:

1. Takes a cooldown period (in seconds), a depends_on reference, and next_steps as input
2. Tracks the timestamp of the last execution using an internal state variable
3. Calculates the current time:
4. For video processing: Uses video metadata (frame number and FPS) to compute a video-time-based timestamp when video_reference_image is provided
5. For other contexts: Uses system clock time (datetime.now())
6. Compares the time elapsed since the last execution against the cooldown_seconds threshold
7. If sufficient time has passed (elapsed time >= cooldown_seconds):
8. Updates the last execution timestamp
9. Continues execution to the specified next_steps blocks, allowing downstream processing
10. If insufficient time has passed (elapsed time < cooldown_seconds):
11. Terminates the current workflow branch, preventing downstream execution until the cooldown period expires
12. 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¶

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

Available Connections¶

Input and Output Bindings¶

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

{
    "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"
}