How It Works

This page walks through the full lifecycle — from signing up to enforcing a ban list in your WAF — so you know exactly what Throttled.IO does and where it sits in your stack.

1. No proxying — zero deployment risk

Throttled.IO never sits in the request path. It does not act as a reverse proxy, gateway, or middleware. Your traffic flows exactly as it does today.

Instead, you ship your existing access logs to Throttled.IO asynchronously. This means:

No single point of failure introduced by the product
No added latency on your requests
Safe to adopt incrementally — start with one service, expand later

After creating an account you receive an API key. The key authenticates all log ingestion and API calls.

3. Invite your team

The account creator is automatically assigned the Admin role. Admins can invite additional users and assign them one of three roles:

Role	Access
Admin	Full access: manage detectors, review and approve reports, manage bans and allowlists, invite users
Billing	Billing and subscription management only
Viewer	Read-only access to reports, dashboards, and ban lists

4. Ship your logs

Send your access logs to the /logs endpoint. Each event represents a single HTTP request your service handled.

Single-event ingest

cURL

curl -X POST https://api.throttled.io/logs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.42",
    "method": "GET",
    "path": "/api/user/123",
    "status": 200,
    "hostname": "api.example.com",
    "timestamp": "2026-05-24T03:17:44Z"
  }'

JavaScript / Node.js

await fetch('https://api.throttled.io/logs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ip: req.ip,
    method: req.method,
    path: req.path,
    status: res.statusCode,
    hostname: req.hostname,
    timestamp: new Date().toISOString(),
  }),
});

Batch ingest

For high-volume services, use the /logs/batch endpoint and send multiple events in a single request. The payload is an array of the same event objects:

curl -X POST https://api.throttled.io/logs/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "ip": "203.0.113.42",
      "method": "GET",
      "path": "/api/user/123",
      "status": 200,
      "hostname": "api.example.com",
      "timestamp": "2026-05-24T03:17:44Z"
    },
    {
      "ip": "198.51.100.7",
      "method": "POST",
      "path": "/api/auth/login",
      "status": 401,
      "hostname": "api.example.com",
      "timestamp": "2026-05-24T03:17:45Z"
    }
  ]'

A 200 response means all events were accepted. Any other status code indicates a failure — retry the request.

You can forward logs in real time from your application, batch-ship them from your load balancer, or replay historical logs to backfill analysis.

5. Configure your detectors

Detectors define what counts as abusive behaviour. You control which detectors are active and how sensitive they are.

Use a built-in template

Pick from ready-made templates for the most common abuse patterns:

Template	What it catches
Profile scraper	IPs harvesting user profiles across many distinct hours
Data harvester	IPs systematically hitting data endpoints at high frequency
Auth brute-force	IPs hammering login or authentication endpoints
Always-on bot	IPs active around the clock with high total request volume

Define a custom detector

Build your own rule when your traffic patterns are specific to your product. A custom detector is defined by three parameters:

Endpoint pattern — a path or regex to match (e.g. /api/user/.*)
Request threshold — the minimum number of hits that triggers the flag (e.g. > 500 requests)
Time window — the period over which hits are counted (e.g. within 24 hours)

Multiple conditions can be combined — for example: more than 200 requests to /api/search/.* across at least 20 distinct hours within a 7-day window.

Suggested rules

Instead of guessing thresholds, let Throttled.IO propose them. Based on your ingested traffic, the platform builds a baseline of what normal user behaviour looks like — how many requests a typical IP makes in a given window, how many distinct paths it touches, how many hours it stays active — and then surfaces IPs that fall significantly outside those norms.

For each outlier pattern, it generates a ready-to-use detector rule pre-filled with thresholds derived from your data. Each suggestion shows:

The observed baseline — e.g. 95th percentile user: 35 requests/day across 6 distinct paths
The outlier behaviour — what makes the flagged traffic stand out from that baseline
A proposed rule — endpoint pattern, request threshold, and time window, ready to enable as-is or adjust before activating

This is especially useful when onboarding a new service (where you have no prior intuition about normal usage) or when your traffic mix shifts and existing rules need recalibration.

Multi-service setup

Each detector can be scoped to one or more hostnames using a regex pattern. Detectors without a hostname pattern apply to all ingested traffic.

Hostname pattern: api(-v\d+)?\.example\.com
Matches:          api.example.com, api-v1.example.com, api-v2.example.com

Each scoped detector maintains its own ban list. Individual services poll the ban list for their detector scope (see step 9) to stay in sync independently.

6. Review analytic reports

Throttled.IO generates analytic reports on a schedule — hourly, daily, or at other intervals. Each report gives you a full picture before you take any action.

What a report contains

Volume — number of flagged IPs, unique countries, and unique ASNs
Access patterns — which endpoints were targeted, at what frequency, and across what time distribution
Traffic share — what percentage of your total request volume the flagged IPs represent, with a per-IP, per-ASN, and per-subnet breakdown
Recommended action — for each flagged cluster, one of:
- Ban the IP
- Ban the ASN (blocks all subnets belonging to that network)
- Send an abuse report to the network owner

How recommendations are determined

The recommended action depends on the origin of the traffic:

Origin type	Recommendation	Rationale
Cloud / hosting provider	Ban ASN or subnet	High confidence the entire range is adversarial; collateral impact is low
ASN with very few subnets	Ban entire ASN	A small footprint means minimal collateral risk — banning the whole ASN is safe and prevents the attacker from rotating across their remaining addresses
Residential ISP / mobile	Send abuse report	Blocking the whole ISP would affect legitimate users; better to let the provider act
Data centre, no ban preferred	Send abuse report	Escalates to the DC without impacting other tenants on the same range

Automated bans

By default, acting on a report requires a manual decision. Once you are confident in a detector's accuracy, you can enable automated bans for that specific detector — flagged addresses are then added to the ban list immediately when the report is generated, with no human step required.

This setting is configured per detector, so you can auto-ban on high-confidence rules (e.g. auth-bruteforce) while keeping others on manual review (e.g. profile-scraper).

7. Get alerted

When a new report is generated, Throttled.IO sends an alert to your configured Slack channel or email address. If automated bans are enabled for the detector, the alert also confirms which addresses were added to the ban list.

Configure your notification preferences in the account settings.

8. Inspect traffic in the dashboard

Before acting on a report, use the traffic dashboard to understand what the flagged traffic actually looks like.

What the dashboard shows

RPS chart — requests per second over your selected time range
IP breakdown — top source IPs by request count, with path-level drill-down
Path breakdown — most-targeted endpoints
Hostname breakdown — request distribution across your services

Report overlay

Apply a report as an active filter to narrow every table and chart to the flagged traffic only. The RPS chart overlays the flagged subset on top of total traffic, making it immediately clear what share of your volume the flagged addresses represent.

Within a report, each flagged IP, subnet, and ASN shows:

Its request count for the period
Its share of total requests during the same window

The dashboard covers up to 30 days of history and reflects ingested events within a few minutes of receipt.

9. Send abuse reports

When the recommended action is to notify the network owner, Throttled.IO generates a ready-to-send email template pre-filled with:

Your details and the affected service
The flagged IP addresses and the observed behaviour
Timestamps and request counts as evidence
The network owner's abuse contact (resolved automatically via RDAP)

You review the template, adjust as needed, and forward it directly to the provider. This is the most effective path when attackers are using residential networks or when a full ASN ban would cause unacceptable collateral damage.

10. Manage allowlists and trusted sources

The allowlist lets you permanently exclude addresses from both detection and enforcement. Entries can be added at any granularity:

Scope	Example use case
Individual IP	A developer's workstation running automated tests
CIDR subnet	Your office network or CI/CD infrastructure
ASN	A specific cloud provider you explicitly trust
Country	A region where you have no users and want excluded from signals

Allowlisted addresses are also how trusted sources are managed — search engine crawlers, social media preview bots, and internal company ranges added to the allowlist are automatically ignored by all detectors.

Allowlists are managed from the Throttled.IO UI. Entries take effect immediately.

Cleaning up false bans

If an address was added to the ban list incorrectly, you can remove it directly from the ban list view in the UI. Add it to the allowlist afterwards to prevent it from being flagged again.

11. Bans are recorded in the Ban List

When you act on a recommendation to ban an IP or ASN — either manually or through automated bans — the affected addresses are added to your Ban List. Every entry is recorded with:

The banned IP, subnet, or ASN
The reason (which detector triggered, which report)
The timestamp

The Ban List is the handoff point between Throttled.IO's analysis and your enforcement layer.

12. Consume the Ban List in your WAF

Fetch your current Ban List at any time via the /banlist endpoint and feed it directly into your WAF, firewall, or CDN. There are no rate limits on this endpoint — poll as frequently as your setup requires, and cache the response if it suits your architecture.

JSON format

GET https://api.throttled.io/banlist
Authorization: Bearer YOUR_API_KEY

[
  { "subnet": "203.0.113.0/24", "asn": 64496, "reason": "profile-scraper", "banned_at": "2026-05-24T04:00:00Z" },
  { "subnet": "198.51.100.0/22", "asn": 64497, "reason": "auth-bruteforce", "banned_at": "2026-05-23T12:30:00Z" }
]

iptables format

GET https://api.throttled.io/banlist?format=iptables
Authorization: Bearer YOUR_API_KEY

-A INPUT -s 203.0.113.0/24 -j DROP
-A INPUT -s 198.51.100.0/22 -j DROP

The iptables response can be piped directly into a shell script or consumed by your firewall automation. Poll the endpoint on a schedule to keep your enforcement layer in sync with the latest ban decisions.

1. No proxying — zero deployment risk​

2. Sign up and get an API key​

3. Invite your team​

4. Ship your logs​

Single-event ingest​

Batch ingest​

5. Configure your detectors​

Use a built-in template​

Define a custom detector​

Suggested rules​

Multi-service setup​

6. Review analytic reports​

What a report contains​

How recommendations are determined​

Automated bans​

7. Get alerted​

8. Inspect traffic in the dashboard​

What the dashboard shows​

Report overlay​

9. Send abuse reports​

10. Manage allowlists and trusted sources​

Cleaning up false bans​

11. Bans are recorded in the Ban List​

12. Consume the Ban List in your WAF​

JSON format​

iptables format​