PULSE API

Programmatic access to live Whatnot market intelligence · Base URL https://pulsemetric.live

1. Versioning & stability

/api/v1/* is the supported programmatic surface and follows an additive-only stability promise: fields are never removed, renamed, or re-typed within v1. New fields may appear at any time, so parse tolerantly. The unversioned /api/* paths serve the web dashboard and behave identically today, but only /api/v1 carries the compatibility promise. GET /api/v1 returns a small JSON index pointing back to this page.

2. Authentication

Pro subscribers get an API key (wn_live_…), shown once at checkout and emailed. Present it one of these ways:

• Recommended: Authorization: Bearer wn_live_…
• X-API-Key: wn_live_…
• ?key=wn_live_…, no longer accepted (removed 2026-09-02). Query strings land in proxy logs, Referer headers and browser history, so a key sent that way should be treated as exposed. A request carrying ?key= now gets 401 {"error":"api_key_in_query_string"} naming the headers above — refused loudly rather than quietly answered as an anonymous caller. Rotate any key you have used in a URL.

curl -H "Authorization: Bearer wn_live_xxxxxxxx" \
  "https://pulsemetric.live/api/v1/top-shows?slug=sports_cards"

No key → you are an anonymous caller: the public endpoints below work, and every other endpoint returns 402 pro_plan_required (the body carries upgrade_url). Endpoints are public or Pro; there is no anonymous teaser tier that serves partial market data. A key that is presented but not recognized (e.g. rotated away) returns 401 invalid_api_key, so always use the newest key from your last rotation. Lost it? Email [email protected].

3. Rate limits

• 120 requests / 60 s per IP (all /api/* traffic).
• 240 requests / 60 s per API key (on top of the per-IP bucket).

Over a limit you get 429 with a Retry-After header and body {"error":"rate_limited","scope":"ip"|"api_key","retry_after":<seconds>}. Back off for retry_after seconds.

4. Polling guidance

Market data updates once per collection sweep, about once an hour (the cadence flexes with load). Polling faster than that returns the same data and burns your budget. GET /api/me returns poll_after_ms, the server's live back-pressure hint; well-behaved clients wait at least that long between polls. Most public per-sweep endpoints also carry Cache-Control headers you can honor.

5. Errors

Errors are JSON with a snake_case error code and usually a human-readable message:

{"error": "seller_not_found", "name": "nosuchseller", "message": "No data for that seller handle."}

6. Endpoints (GET)

Two tiers: public no key needed · pro requires a Pro API key (else 402). All paths below also exist under /api/v1/….

Market-wide

Per-seller

Unknown-seller behavior

These are intentional and stable, so code against them. They describe an authenticated call; without a Pro key the Pro rows below answer 402 before they ever look the handle up:

• /api/seller?name=…, /api/seller-cadence, /api/seller-reach → 404 {"error":"seller_not_found"}
• /api/seller-stats?name=… → 200 {} (empty object)
• /api/seller/<handle>/recap → 200 {"recap": null}
• /api/seller-teaser?name=… → 200 {"found": false, …} (still carries a market-wide best window)

7. Support

Questions, key re-issues, or a field you wish existed: [email protected].