API

Free, keyless JSON for IRC networks and channels: find them, connect to them, and see how busy they are. Build it into your client, your bot or your site.

Discovery Find networks and channels Browse or search every network we track, search channels by name or topic, and get a ready-to-open ircs:// link. Stats Live numbers and history People online, rank, peaks and trends for any network or channel, with history from the last day to all time. Members Your network's private analytics Run a network? Make a personal key and pull its peak hours, channel churn and daily history into your own tools.

Ready-made scripts

Don't want to write code? These add an IRC network finder to your client, using this API.

erkSearch for mIRC

A search window: find networks by keyword or tag, best match first, sort them, see their details and connect with a click. Needs mIRC 7.56 or newer.

Install: save the file, then in mIRC type /load -rs erksearch.mrc and open it with /erksearch.

Download erksearch.mrc

erkSearch for HexChat

Commands to search networks by keyword or tag, browse the biggest, read their details and connect by number. Needs HexChat's Lua plugin and curl.

Install: put the file in HexChat's addons folder (or /lua load it), then type /erksearch libera.

Download erksearch.lua

erkSearch for irssi

The same commands for irssi: search networks by keyword or tag, browse the biggest, read their details and connect by number. Searches run in the background, so irssi never stalls.

Install: save the file to ~/.irssi/scripts/, type /script load erksearch, then /erksearch libera.

Download erksearch.pl

Built with the erkstats API

Built a client feature, bot, script or site on the API? Tell us about it and we'll list it here.

Reference

A free, keyless read API for the data you see on erkstats: IRC networks and channels, how to connect to them, and how busy they are. Use it to add a "find a network" feature to an IRC client, show live numbers on your site, or build a bot that reports on your favourite network.


Name your app

Please tell us what is calling, with an X-Client header (or a User-Agent):

X-Client: my-irc-client/2.1

It is optional, but it lets us see which apps use the API, keep them working when things change, and get in touch if something goes wrong. If you build something people can use, tell us and we will list it on the API page.


Finding networks and channels

GET /networks

Browse networks: the top N by a sort, or the whole list.

ParamTypeDefaultNotes
sortstringusersOne of users, users_30d, channels, servers, founded, name.
dirstringdescasc or desc. (Use sort=name&dir=asc for A to Z.)
langstring-Only networks that list this language, e.g. lang=german.
verifiedint-verified=1 returns only networks that have opted in.
limitint251 to 500. Use limit=500 to get them all.
offsetint0For paging.

users is the count right now and moves around through the day; users_30d (the 30-day average) gives a steadier "biggest networks" order.

GET /api/v1/public/networks?sort=users_30d&limit=3
{
  "count": 154,
  "limit": 3,
  "offset": 0,
  "sort": "users_30d",
  "dir": "desc",
  "results": [ /* network objects, see below */ ]
}

Search networks and channels together, with the same results as the Search page. It finds:

Results come back best match first. Both lists are bigger networks and busier channels first where the match is equally good.

ParamTypeDefaultNotes
qstring-What to search for, at least 2 characters. Up to 6 words are used.
tagstring-Only networks with this tag, and their channels, e.g. tag=gaming. q can be left out when this is given.
sortstringrelevancerelevance (best match), users or name.
dirstring-asc or desc. The default is desc, but asc (A to Z) for name.
network_limitint10How many networks to return, 1 to 100.
limitint25How many channels to return, 1 to 100.
offsetint0For paging through the channels.
GET /api/v1/public/search?q=science&network_limit=2&limit=1
{
  "query": "science",
  "tag": null,
  "sort": "relevance",
  "dir": "desc",
  "also_matching": ["biology", "mathematics", "physics", "scientific"],
  "networks": {
    "count": 1,
    "limit": 2,
    "results": [ /* network objects */ ]
  },
  "channels": {
    "count": 92,
    "limit": 1,
    "offset": 0,
    "results": [ /* channel objects, each with its network */ ]
  }
}

also_matching lists the other words that found results: other forms of your words, related words, and longer words starting with yours. Show it the way the Search page does ("Also matching: biology, physics...") so people can see why a result turned up.

GET /search/network

Just the networks, with paging. It takes the same q and tag as /search, and the lang and verified filters from /networks.

ParamTypeDefaultNotes
qstring-At least 2 characters (or give tag).
tagstring-Only networks with this tag.
sortstringrelevancerelevance, or any /networks sort: users, users_30d, channels, servers, founded, name.
dirstringdescasc or desc (not used with relevance).
langstring-Only networks that list this language.
verifiedint-verified=1 returns only networks that have opted in.
limitint251 to 100.
offsetint0For paging.
GET /api/v1/public/search/network?q=libera

Returns a list (see Conventions) with query, tag, sort, dir and also_matching, and network objects as results.

GET /search/channel

Just the channels, with paging, across every network (or one).

ParamTypeDefaultNotes
qstring-At least 2 characters (or give tag).
tagstring-Only channels on networks with this tag.
networkstring-Only channels on this network, by its slug, e.g. network=libera.
sortstringrelevancerelevance, users or name.
dirstring-asc or desc. The default is desc, but asc for name.
limitint251 to 100.
offsetint0For paging.

Each result is a channel object with its network inside it.

GET /api/v1/public/search/channel?q=linux&limit=1
{
  "query": "linux",
  "tag": null,
  "count": 1083,
  "limit": 1,
  "offset": 0,
  "sort": "relevance",
  "dir": "desc",
  "also_matching": ["debian", "ubuntu", "unix"],
  "results": [
    {
      "name": "#linux",
      "topic": "Welcome to #linux! ...",
      "users": 2452,
      "users_30d_avg": 2495,
      "channel_stats": false,
      "connect_uri": "ircs://irc.libera.chat:6697/#linux",
      "network": { /* network object */ }
    }
  ]
}

Network and channel stats

The numbers behind each network and channel page. <slug> is the network's slug from any network object (it is also the last part of its page address, e.g. erkstats.info/network/libera).

GET /networks/<slug>

One network, with its current stats.

GET /api/v1/public/networks/libera
{
  "slug": "libera",
  "name": "Libera.Chat",
  "server": "irc.libera.chat",
  "port": 6697,
  "tls": true,
  "users": 30429,
  "users_30d_avg": 31072,
  "connect_uri": "ircs://irc.libera.chat:6697/",
  "url": "https://erkstats.info/network/libera",
  "stats": {
    "users": 30429,
    "channels": 22787,
    "servers": 30,
    "users_change_24h_pct": -0.4,
    "users_trend_30d_pct": -3.8,
    "rank": 1,
    "rank_of": 154,
    "peak": { "users": 35273, "at": "2026-08-15T09:25:48Z" },
    "tracked_since": "2026-07-25T06:37:13Z",
    "updated_at": "2026-11-04T04:08:45Z"
  }
}

(Shortened: it carries every field of the network object, plus url and stats.)

StatMeaning
usersPeople online at the last check.
channelsChannels the network reported at the last check.
serversServers in the network.
users_change_24h_pctChange in people online against the same time yesterday.
users_trend_30d_pctChange over the last 30 days.
rank, rank_ofPosition by people online, out of all the networks we track.
peakThe most people we have ever seen online, and when.
tracked_sinceOur first reading for this network.
updated_atWhen the numbers were last checked (every few hours).

GET /networks/<slug>/history

People online over time.

ParamTypeDefaultNotes
rangestring30dOne of 24h, 7d, 30d, 1y, 10y, all.
fromstring-Instead of range: a start date (2026-10-01, UTC) or unix time.
tostringnowWith from: an end date (inclusive) or unix time.
GET /api/v1/public/networks/libera/history?range=7d
{
  "network": "libera",
  "range": "7d",
  "from": null,
  "to": null,
  "points": [
    { "t": "2026-10-28T07:13:26Z", "users": 30908 },
    { "t": "2026-10-28T09:14:18Z", "users": 31490 }
  ]
}

You get up to about 180 points whatever the range: over long ranges, nearby readings are averaged together.

GET /networks/<slug>/channels

The network's busiest channels right now.

ParamTypeDefaultNotes
limitint251 to 100.
{
  "network": "libera",
  "listed": true,
  "count": 6890,
  "limit": 3,
  "results": [
    {
      "name": "#linux",
      "topic": "Welcome to #linux! ...",
      "users": 2374,
      "channel_stats": false,
      "connect_uri": "ircs://irc.libera.chat:6697/#linux",
      "url": "https://erkstats.info/channel/libera/#linux"
    }
  ]
}

Some networks ask us not to publish their channel list. For those, listed is false and results is empty.

GET /networks/<slug>/channel?name=<channel>

One channel, with its 30-day average, its peak and when we first and last saw it. Put the channel name in name, with the # written as %23:

GET /api/v1/public/networks/libera/channel?name=%23linux
{
  "name": "#linux",
  "topic": "Welcome to #linux! ...",
  "users": 2374,
  "channel_stats": false,
  "connect_uri": "ircs://irc.libera.chat:6697/#linux",
  "url": "https://erkstats.info/channel/libera/#linux",
  "users_30d_avg": 2396,
  "peak": { "users": 2535, "at": "2026-07-26T19:20:01Z" },
  "first_seen": "2026-07-25T06:37:13Z",
  "last_seen": "2026-11-04T04:08:45Z"
}

GET /networks/<slug>/channel/history?name=<channel>

People in a channel over time. Takes the same range, from and to as the network history, and returns the same shape with a channel field.


Objects

Network object

FieldTypeDescription
slugstringStable identifier. Use it rather than name to link or store a network.
namestringDisplay name.
serverstringThe public server address to connect to.
portintPort.
tlsboolWhether the port uses TLS.
websitestring or nullThe network's website.
webchatstring or nullA web page where you can chat without installing a client.
foundedint or nullYear founded.
languagestring or nullMain language (e.g. "English"), the first of languages.
languagesstring[]Every language the network lists, main one first (may be empty).
blurbstring or nullShort description.
usersint or nullPeople online at the last check.
users_30d_avgint or nullAverage people online over the last 30 days.
verifiedboolThe network has confirmed it is happy to be listed (see below).
socialsobject or nullLinks to the network's social accounts, e.g. {"mastodon": "https://..."}.
connect_uristringReady to open: ircs://host:port/ (or irc:// without TLS).

Channel object

FieldTypeDescription
namestringChannel name, including the leading #.
topicstring or nullLatest topic.
usersint or nullPeople in the channel at the last check.
users_30d_avgint or nullAverage over the last 30 days.
channel_statsbooltrue if erkstats has a full statistics page for this channel.
connect_uristringReady to open: ircs://host:port/#channel.
networkobjectThe network it is on (search results only).

connect_uri keeps the # of a channel as it is (e.g. ircs://irc.libera.chat:6697/#linux), which is what IRC clients expect. Hand it straight to your client.

verified means the network's operators have confirmed they are happy to be listed and checked by us. Unverified networks are still tracked and returned; the flag just lets you highlight the ones that opted in.


Conventions

Lists come back as:

{ "count": 154, "limit": 25, "offset": 0, "results": [ ... ] }

count is the total number of matches, not the number returned, so you can page with limit and offset until offset + results.length >= count. Searches add "query", "tag" and "also_matching"; the network lists and searches add "sort" and "dir".

Times are UTC, written like 2026-11-04T04:08:45Z.

Errors are {"error": "..."} with an HTTP status:

StatusWhen
400A required parameter is missing or wrong (e.g. q too short).
404Unknown network, channel or endpoint.
405A method other than GET.
429Too many requests. Wait for the Retry-After seconds.
503/search only: search is starting up after an update. Try again in a few minutes.

Rate limit. 120 requests a minute per IP address. Numbers only change every few minutes, so cache what you fetch and you will stay well under it.


Notes