LurkAPI

What is this?

LurkAPI lets your Twitch chat track who is lurking using custom bot commands. When a viewer runs !lurk, the bot records the time. When they run !unlurk, the bot reports how long they were away.

Works with Nightbot (auto-injected headers), and all other major bots via ?user= and ?channel= query parameters. Data is stored per-channel. Lurkers inactive for more than 24 hours are automatically pruned.

API Endpoints

All endpoints are GET requests under /api/. Pass identity via Nightbot headers (automatic) or ?user=NAME&channel=NAME query params.

Method	Path	Description	Response example
GET	/api/lurk	Start lurking (visible confirmation)	`StreamerName started lurking`
GET	/api/lurksilent	Start lurking (no chat message)	silent — returns a single space
GET	/api/unlurk	Stop lurking with full message	`StreamerName stopped lurking after 1:23:45`
GET	/api/unlurktime	Stop lurking, return duration only	`1:23:45`
GET	/api/lurkers	List all current lurkers in the channel	`Current Lurkers: Alice, Bob, Charlie`

Bot Setup

Select your bot to see the correct command syntax. Add each as a custom command in your bot’s dashboard.

Your bot:

!lurk — start lurking (shows a message)

!lurk — start lurking (silent, no chat response)

!unlurk — stop lurking (full message)

!unlurk — stop lurking (time only — embed in a custom message)

!lurkers — list everyone currently lurking

How it works

The bot calls a URL when a viewer uses a command. LurkAPI reads the viewer’s username and channel from the request, updates the lurk record in the database, and returns a plain-text response that the bot posts to chat.

Nightbot automatically attaches identity via Nightbot-User and Nightbot-Channel request headers — no query parameters needed. All other bots include the viewer’s username and channel name directly in the URL using that bot’s variable syntax.

Lurk times are stored as Unix timestamps. Duration is calculated at unlurk time. Entries older than 24 hours are automatically removed when /api/lurkers is called.