ACTION_ID: rate_limiter
NAME: Rate Limiter
CATEGORY: Floq Tools
CREDITS: 0

Throttle how fast rows move down the chain. Releases at most the
configured number of rows per unit of time, evenly spaced — the pressure
valve in front of a rate-limited destination.

1. INPUTS

requests (type: number, required)
  Requests. How many rows to release per unit of time. Whole number,
  at least 1. Rates above 25 rows per second are not supported.

per (type: string, required, resolve: enum)
  Per. The unit of time the request count applies to. Releases are
  spread evenly across the unit, never sent as a burst.
  Values:
    - { value: "second", label: "Second" }
    - { value: "minute", label: "Minute" } (default)
    - { value: "hour", label: "Hour" }
    - { value: "day", label: "Day" }

2. OUTPUTS

released_at (string) — ISO timestamp of the moment the row passed the
rate limiter and was released to the next step. Empty while the row is
still waiting — the next steps are blocked until it is set.

3. HOW TO CONFIGURE

Configure Action body:

{
  "inputs": {
    "requests": "100",
    "per": "minute"
  }
}

Field-by-field:
  - requests  Required. Whole number, at least 1. Pass as a quoted
              string — Configure Action ignores raw JSON numbers.
              Rates above 25 rows per second are not supported.
  - per       Required. `second`, `minute`, `hour` or `day`.

4. KEY NOTES

- `requests` is a number field. Pass it quoted (`"100"`); a raw JSON
  number is dropped with an `unknown_field` warning and the field stays
  unset.
- Releases are evenly spaced, never bursty — 100 per minute means one
  row every 0.6 seconds.
- It counts rows LEAVING this step. A downstream step that fans one row
  into many is not individually limited, so place the limiter directly
  in front of the step you are protecting.
- Waiting rows show a rate-limited status and block their own downstream
  cells. `released_at` stays empty until the row is let through, so it
  doubles as a readiness marker.
- Rates above 25 rows per second are rejected.

5. WHERE IT FITS IN A WORKFLOW

Pattern: ... -> rate_limiter (requests 60, per minute) -> http_api_call,
when the upstream API caps you at 60 requests a minute.

6. WHEN TO USE

Use rate_limiter in front of any step that hits a third-party rate limit
— a partner API, a customer's CRM, a webhook endpoint that drops bursts.

7. WHEN NOT TO USE

Need a fixed pause per row rather than a throughput cap
  -> action-detail/delay_step.txt

Need to stop some rows entirely rather than slow them
  -> action-detail/filter.txt

Last updated: 2026-08-03.