Aggregates that mirror the public website need no key. Every event-level or bulk surface — event lists and details, per-event streaming, exports (including the CC BY 4.0 sample), canaries and prompts — requires a key issued after a human approves a request. Gated event data, raw data, realtime feeds and training exports are proprietary and require the corresponding scopes and separate licensing terms.
These public GET endpoints return JSON, SSE or NDJSON. Follow a route to inspect its response, or use the curl example below.
GET /api/v1/stats/overviewRequest totals, AI-category share, leading bots and sensor status. ↗GET /api/v1/stats/timeseries?metric=events&interval=1hTimestamped observations for a chosen metric and interval. ↗GET /api/v1/botsKnown identities and inferred clusters, with confidence and verification. ↗GET /api/v1/eventsEvent rows (approved key required); read keys get delayed teasers, gated scopes get full detail. ↗GET /api/v1/events/recentAlias of /events, with the same key requirement and scopes. ↗GET /api/v1/streamSSE (approved key required); aggregate SSE with a read key, per-event SSE with stream or raw scope. ↗GET /api/v1/export?format=ndjsonCC BY 4.0 sample of at most 1,000 rows with an approved read key, including synthetic watermark rows. ↗GET /api/v1/regionsSensor availability and observed regional volume. ↗GET /api/v1/robots-complianceControlled robots.txt rule tests and observed compliance. ↗GET /api/v1/canariesRecorded canary follows with attribution uncertainty. ↗Use the observation window, access date and verification state when citing results. CC BY 4.0 applies strictly to samples and aggregates, obtainable with an approved read key; full exports require export or raw scope. Anonymous calls to event-level or bulk endpoints return 401 with a link to the request form below. A query parameter never grants a scope.
Send a verified key as Authorization: Bearer <key>. Scopes are independent permissions; raw includes every gated capability. A read key keeps the public delay and field restrictions.
| Scope | Access |
|---|---|
| Anonymous | Aggregates that mirror the public website only (stats, regions, reports, robots-compliance aggregates, known bots, bot directory and profiles). Event-level and bulk endpoints return 401. |
| read | Approved key: aggregates, CC BY 4.0 export samples and delayed event teasers, with higher quotas. |
| events | Gated event lists and details, sensitive metadata and IP filtering. |
| stream | Gated event access and per-event SSE. |
| export | Gated event access and full JSON, CSV or NDJSON export, up to 100,000 rows per call. |
| raw | All gated capabilities, raw IPs and payload/training export with format=jsonl. |
Gated access does not grant redistribution or training rights. Contact help@mothlight.ai for access and licensing terms.
Public event lists allow 50 rows per page and 200 rows per window. The window spans at most 24 hours and ends at least 60 minutes ago. Public details omit query, headers, body, hashes, JA4, precise geo, signal weights and signal detail. IP filtering requires a gated event scope. Gated lists allow 200 rows per page.
| Route group | Anonymous | read | Gated key |
|---|---|---|---|
| Events, bot events, canaries, prompts | 20 / 200 | 120 / 2,000 | 120 / 20,000 |
| SSE connections | 6 / 100 | 30 / 1,000 | 30 / 10,000 |
| Export calls | 2 / 10 | 10 / 100 | 10 / 1,000 |
Other public GETs default to 60 requests per minute anonymously and 600 with a verified key, subject to that key's configured limit. Events, bot events, canaries and prompts share a daily quota; SSE and export have separate daily quotas. Rate and daily-limit headers describe the active limits; 429 responses include Retry-After. Authenticated responses, streams and exports are not cached.
With a read key, SSE contains minute/category aggregate cells only when at least three events and two source buckets contribute. Heartbeats arrive every 15 seconds; reconnect after the 60-second connection limit. Keyed export samples suppress small hour/category cells and include synthetic watermark rows for provenance, not observed attacks.
Explore threat patterns, read about Mothlight and SEWORKS, or contact the team.
Keys are issued only after a human approves a request. Tell us who you are, what you plan to build or study, and which tier you need. If approved, we will send your key and terms by email; the key is shown to you once.
A public API for reproducible research. Cite the window, the method, and the uncertainty.
curl -s 'https://mothlight.ai/api/v1/stats/overview'JSON · CC BY 4.0