# Pulse

> A small, free, agent-first API. Give a public post URL, get normalized views,
> likes, comments, and publish date as JSON. No signup, no API key.

Base URL: https://pulse.walls.sh
Pricing: free (Pulse also speaks x402 for per-call USDC payment, currently off)
Payment: x402 (HTTP 402) is supported so an agent can pay per call in USDC and retry with no human in the loop. Off by default — calls are free.
CORS: enabled for all origins — browser apps can call Pulse directly.
Rate limit: every response carries RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset (per minute) — self-throttle on Remaining instead of waiting for a 429.

## Endpoint

GET https://pulse.walls.sh/metrics?url=<public post url>
  -> { platform, views, likes, comments, shares, viewsEstimated, publishedAt, title, author, thumbnail }
  shares = reshares (X retweets, TikTok shares, Bluesky reposts); null where the platform doesn't expose it.
  Short links (vm.tiktok.com/…, tiktok.com/t/…, t.co/…) are resolved automatically; the response's url is the canonical post URL.
  Errors: 400 bad/unsupported url · 402 payment required (only if billing on) · 404 content_unavailable (deleted/private) · 422 login_required (instagram/threads/linkedin) · 429 rate_limited (respect Retry-After) · 502 fetch_failed

GET https://pulse.walls.sh/metrics/batch?url=<a>&url=<b>   (or ?urls=<a>,<b>,<c>; max 50)
  -> { count, results: [ {…post or profile metrics} | { url, error } ] }  (mixed batches OK; order preserved; one bad URL never fails the batch)

GET https://pulse.walls.sh/history?url=<post or profile url>[&since=<ISO-8601 or unix ms>]
  -> { url, platform, kind: "post"|"profile", count, points }   (since= returns only points after that moment — poll the delta)
  Posts: { t, views, likes, comments } per fresh /metrics fetch. Profiles: { t, followers, posts } per fresh /profile fetch.
  Repeat lookups build the growth curve over time.

GET https://pulse.walls.sh/account/usage   (Authorization: Bearer <your API key>)
  -> { plan, limitPerMin, calls, calls_24h }   your own key's usage

GET https://pulse.walls.sh/profile?url=<profile url>
  -> { platform, handle, name, followers, following, posts, likes, verified, avatar }
  Account-level metrics. Live: YouTube, TikTok, Instagram, X, Bluesky. Threads/LinkedIn profiles -> 422 login_required.

## Platforms

- YouTube: Live (views · likes · date)
- X / Twitter: Live (views · likes · comments · shares · date)
- TikTok: Live (views · likes · comments · shares · date)
- Bluesky: Live (likes · comments · shares · date)
- Instagram: Beta (likes · comments · views)
- Threads: Soon (needs login)
- LinkedIn: Soon (needs login)

## Discovery

- OpenAPI: https://pulse.walls.sh/openapi.json
- Docs:    https://pulse.walls.sh/docs
- Stats:   https://pulse.walls.sh/stats   (live usage JSON; https://pulse.walls.sh/status for humans)
- Health:  https://pulse.walls.sh/health
- MCP:     npx -y pulse-mcp   (Model Context Protocol server; tools: metrics, metrics_batch)