Your first API call in five minutes

Create a key, call the API and understand access, responses and limits.

1. Start free

Start free, then open the Console. Public access is free; approved Researcher access is also free. A free account does not unlock the Events API. You can complete the overview call immediately and run the events call after your organization has Professional or Enterprise access.

2. Create an API key

Open Console → API keys. An owner or admin can create a named key for your organization. Copy the secret when shown and store it privately; it is shown only once. Use YOUR_API_KEY in the examples below as a placeholder, replacing it locally. Keep keys out of source control, screenshots and shared notebooks. Members should ask an owner or admin to create a key.

3. Call the API

These examples use the brand API host. No requests are made by this documentation page. The overview endpoint is public; passing your key also lets you verify authenticated access. The second endpoint requires Professional or Enterprise and the events scope. A Public or Researcher key receives 403 on the events call; no key receives 401.

curl

curl --fail-with-body -H "Authorization: Bearer YOUR_API_KEY" \
  'https://mothlight.ai/api/v1/stats/overview'
curl --fail-with-body -H "Authorization: Bearer YOUR_API_KEY" \
  'https://mothlight.ai/api/v1/events/recent?limit=10'

Python with requests

Install requests in your own Python environment, then run:

import requests

base = "https://mothlight.ai/api/v1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
for endpoint in ("/stats/overview", "/events/recent?limit=10"):
    response = requests.get(base + endpoint, headers=headers, timeout=30)
    response.raise_for_status()
    print(response.json())

JavaScript with fetch

Run this in a trusted server environment. Do not ship a private API key in browser code.

const base = "https://mothlight.ai/api/v1";
for (const endpoint of ["/stats/overview", "/events/recent?limit=10"]) {
  const response = await fetch(base + endpoint, {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(await response.json());
}

4. Read the response

Overview returns updated_at, totals, last_24h, by_category_24h and ai. The ai object includes observation-window and denominator information; use those fields when comparing shares. Event lists return items and next_cursor. Each event carries a UTC ts, category and confidence. A category is a label, not proof of compromise. For example SCN means Scanner, EXP means Exploit bot and UNK means Unknown; see the glossary.

A null next_cursor ends pagination. An empty items array means no accessible results for that window and filter, not that an address or network is safe.

5. Understand access and limits

Public access provides aggregates and a small delayed sample. Researcher provides read access and a bounded sample: up to 500 rows per call, a seven-day sample window, at least 60 minutes of delay and 2,000 sample rows per day. Neither tier grants Events API access.

Professional provides events and stream access with at least 15 minutes of event delay, 30-day event history and 50,000 event/sample rows per key per UTC day. Enterprise provides no minimum event delay and up to 365-day history with 1,000,000 rows per key per day. History is still filling from the network launch on 2026-11-01; a plan cannot supply observations from before collection.

Per-key request limits are 60/minute and 1,000/day for Public keys, 120/minute and 5,000/day for Researcher, 300/minute and 20,000/day for Professional, and 600/minute and 100,000/day for Enterprise. Anonymous endpoints have their own per-IP route limits. Read X-RateLimit-* and X-DailyLimit-* response headers rather than assuming unused capacity.

Troubleshooting and next steps

401 means a missing, invalid, revoked or expired key: check the Bearer header. 403 means the key lacks the required scope or plan: ask an owner to check Billing. 429 means a rate or daily quota was exceeded: honor Retry-After and back off. Errors use an error object with code and message.

Continue with Collect events, Triage an alert IP, the API reference, or FAQ.