Rate Limit Simulator

Overview

You describe the policy — a fixed window, a sliding window, or a token bucket — and hand us the snapshot you already hold: the request timestamps for a window, or the bucket's tokens and last refill for a bucket. We return whether this request fits, what is left, when the window resets or how long to wait, and for a bucket the state you should store next. Every instant comes from your request and the arithmetic is exact decimal, so the same snapshot always gives the same verdict. This is a simulator for planning and testing: it is not Squillify's own limiter, it reads no live counter, and it reserves or consumes nothing — deciding is yours to do with what we return.

Rate-limit bugs are found in production because testing them means waiting for real windows to roll over, and because every service rounds the edges differently. Making the policy and the instant explicit inputs turns throttling into something you can test at the boundary, compare across languages, and explain to a caller.

When to use it

Scope

Non-goals

• Is not Squillify's own rate limiter and cannot authorize a real request
• Does not read, reserve, consume, or mutate any live counter
• Does not store the bucket for you — persist nextState yourself
• Does not read a clock; the instant comes from your request
• Does not send or inspect any HTTP traffic

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"network.rate_limit_check","input":{"key":"api-key:demo","policy":{"type":"FIXED_WINDOW","limit":100,"windowSeconds":60},"timestamp":"2026-07-27T10:00:30Z","requestTimestamps":[]}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("network.rate_limit_check", {"requestTimestamps":["2026-07-27T10:00:05Z","2026-07-27T10:00:12Z","2026-07-27T10:00:29Z"],"timestamp":"2026-07-27T10:00:30Z","key":"api-key:demo","policy":{"limit":100,"type":"FIXED_WINDOW","windowSeconds":60}});

Errors

Other limits

Limitations

• Is not Squillify's own rate limiter and cannot authorize a real request
• Does not read, reserve, consume, or mutate any live counter
• Does not store the bucket for you — persist nextState yourself
• Does not read a clock; the instant comes from your request
• Does not send or inspect any HTTP traffic
• Enforcing a limit on live traffic — the decision here is advisory
• Counting requests for the caller; you supply the history
• Charging Squillify quota, which is metered separately

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "network.rate_limit_check",
  "input": {
    "requestTimestamps": [
      "2026-07-27T10:00:05Z",
      "2026-07-27T10:00:12Z",
      "2026-07-27T10:00:29Z"
    ],
    "timestamp": "2026-07-27T10:00:30Z",
    "key": "api-key:demo",
    "policy": {
      "limit": 100,
      "type": "FIXED_WINDOW",
      "windowSeconds": 60
    }
  }
}

Examples

{
  "requestTimestamps": [
    "2026-07-27T10:00:05Z",
    "2026-07-27T10:00:12Z",
    "2026-07-27T10:00:29Z"
  ],
  "timestamp": "2026-07-27T10:00:30Z",
  "key": "api-key:demo",
  "policy": {
    "limit": 100,
    "type": "FIXED_WINDOW",
    "windowSeconds": 60
  }
}

{
  "allowed": true,
  "observed": 3,
  "retryAfterMs": 0,
  "limit": 100,
  "reasonCode": "ALLOWED",
  "resetAt": "2026-07-27T10:01:00Z",
  "_meta": {
    "evaluatedAt": "2026-07-27T10:00:30Z",
    "algorithm": "FIXED_WINDOW",
    "eventsInWindow": 3,
    "eventsConsidered": 3
  },
  "remaining": 96
}

{
  "key": "user:42",
  "policy": {
    "refillPerSecond": 0.5,
    "type": "TOKEN_BUCKET",
    "capacity": 10
  },
  "bucketState": {
    "tokens": 2,
    "lastRefillAt": "2026-07-27T10:00:00Z"
  },
  "requestCost": 4,
  "timestamp": "2026-07-27T10:00:10Z"
}

{
  "retryAfterMs": 0,
  "nextState": {
    "tokens": 3,
    "lastRefillAt": "2026-07-27T10:00:10Z"
  },
  "allowed": true,
  "_meta": {
    "evaluatedAt": "2026-07-27T10:00:10Z",
    "algorithm": "TOKEN_BUCKET",
    "tokensBeforeRequest": 7,
    "elapsedSeconds": 10
  },
  "reasonCode": "ALLOWED",
  "remaining": 3,
  "capacity": 10
}

Recommended use cases

• Test throttling logic against exact window edges without waiting in real time
• Show a client how long to wait before its next call fits
• Keep one shared rate-limit definition across services that each store their own counters

Avoid for

• Enforcing a limit on live traffic — the decision here is advisory
• Counting requests for the caller; you supply the history
• Charging Squillify quota, which is metered separately

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags