Matrix Public Rooms Extractor

Point at any Matrix homeserver and extract its public room directory — the list of rooms that homeserver publishes to the federation — over the Matrix Client-Server API (GET /_matrix/client/v3/publicRooms). One structured row per public room, paginated through the server's own opaque next_batch cursor.

Works against any Matrix homeserver (Synapse, Dendrite, Conduit, …) — they all speak the same Client-Server directory contract, so one actor reads them all: matrix.org, matrix.tchncs.de, gnome.modular.im, mozilla.modular.im, fedora.ems.host, and thousands more.

What you get

One row per public room, keyed on the always-present room_id:

Field	Description
room_id	Canonical room ID (e.g. !abc:matrix.org) — always present
name	Room display name (nullable — many rooms are unnamed)
topic	Room topic / description (nullable)
canonical_alias	Human alias, e.g. #community:matrix.org (nullable)
num_joined_members	Joined member count (may be 0)
avatar_url	Room avatar mxc:// URI (nullable)
world_readable	Whether history is world-readable
guest_can_join	Whether guests may join
join_rule	e.g. public, knock, invite (nullable)
room_type	e.g. m.space for spaces; null for regular rooms
_homeserverUrl / _server / _page / _rowIndex / _totalRoomCountEstimate	Provenance

Input

Field	Required	Description
homeserverUrl	✅	Homeserver base URL, e.g. https://matrix.org
server		Query a different server's directory through this homeserver (?server=) — usually needs a token
search		Full-text filter over name/alias/topic — uses POST, usually needs a token
roomType		all (default) · spaces (m.space only) · rooms (exclude spaces)
accessToken		Matrix access token — unlocks search / room-type filters / federated queries
maxRecords		Stop after N rooms (default 2000)
pageSize		Rooms per page (default 100; server may cap lower)

Anonymous vs authenticated

The anonymous GET listing works on any homeserver that publishes its directory publicly — no token needed. The Matrix spec routes full-text search, room-type filters, and federated ?server= queries through the POST endpoint, which most homeservers gate behind an access token (they return M_MISSING_TOKEN). Supply accessToken to use those; leave it empty for a plain public-directory listing.

Example

{
  "homeserverUrl": "https://matrix.org",
  "maxRecords": 100
}

Use cases

• Federation monitoring — track which rooms a homeserver publishes over time.
• Community discovery — enumerate spaces and rooms across the Matrix network.
• Moderation intelligence — surface newly-published rooms, aliases, topics.
• Directory research — member-count and room-type distributions per server.

How it works

• Anonymous GET /_matrix/client/v3/publicRooms by default; POST with a filter only when search / roomType is set.
• Opaque-cursor pagination: the response next_batch is echoed as the next request's since; the walk stops when the server omits it. The total_room_count_estimate is treated as a hint, never a page terminator.
• Rate limits (M_LIMIT_EXCEEDED) are honored via retry_after_ms backoff.
• Fails fast (never a fabricated empty success) if the homeserver is unreachable, rejects the query (auth/forbidden), or the directory matched zero rooms.

Pricing

Pay-per-event: $0.0005 per room record (tiered volume discount by subscription tier). You pay only for rooms actually emitted.