---
title: PDS management
---

hydrant rate-limits firehose events per PDS. each PDS is assigned to a named rate tier that controls how aggressively hydrant limits events from it. two built-in tiers are always present: `default` (conservative limits for unknown operators) and `trusted` (higher limits for well-behaved operators). additional tiers can be defined via `RATE_TIERS`.

the per-second limit scales with the number of active accounts on the PDS: `max(per_second_base, accounts × per_second_account_mul)`.

you can also define an optional `account_limit` for a rate tier. if a PDS exceeds this number of active accounts, hydrant will reject any new account creation events from it.

the built-in tiers are:

| tier | per_second_base | per_second_account_mul | per_hour | per_day | account_limit |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `default` | 50 | +0.5 | 3,600,000 | 86,400,000 | 100 |
| `trusted` | 5000 | +10.0 | 18,000,000 | 432,000,000 | 10,000,000 |

tiers are resolved in this order: explicit API assignment (set via `PUT /pds/tiers`, stored in the database, survives restarts), then glob rules (from `TIER_RULES`, evaluated in order; first match wins), then the `default` tier (applied if nothing else matches).

deleting an API assignment reverts the host to glob-rule resolution, not necessarily back to `default`. if a rule like `*.bsky.network:trusted` matches the host, it will become trusted again without any further action.

## GET /pds/tiers

list all current tier assignments alongside the available tier definitions. returns `{ "assignments": [{ "host": string, "tier": string }], "rate_tiers": { <name>: { "per_second_base": int, "per_second_account_mul": float, "per_hour": int, "per_day": int } } }`.

`assignments` only contains PDSes with an explicit API assignment. hosts without one resolve via glob rules or fall back to `default`.

## PUT /pds/tiers

assign a PDS to a named rate tier.

| field | description |
| :--- | :--- |
| `host` | PDS hostname (e.g. `pds.example.com`) |
| `tier` | name of the rate tier to assign; returns `400` if unknown |

assignments are persisted to the database and survive restarts. re-assigning the same host updates the tier in place without creating a duplicate.

## DELETE /pds/tiers

remove an explicit tier assignment for a PDS. query parameter:

| param | description |
| :--- | :--- |
| `host` | PDS hostname (e.g. `?host=pds.example.com`) |

reverts the host to glob-rule resolution (not necessarily `default`; a matching `TIER_RULES` pattern still applies).

returns `200` even if no assignment existed.

## GET /pds/rate-tiers

list the available rate tier definitions. returns a map of tier name to `{ "per_second_base", "per_second_account_mul", "per_hour", "per_day", "account_limit" }`.