API / v1

Build with real
observations.

Start with a public lookup. Every metric includes its observation time, source, precision and scope. Missing values are null, never invented zeroes.

1. Make a public request

No developer key is required for enabled public read endpoints. Service and provider limits apply. Do not send platform credentials.

curl "https://stratus-social.kc3wca.workers.dev/v1/profiles/bluesky/akasammythepuppy.me"

const response = await fetch("https://stratus-social.kc3wca.workers.dev/v1/profiles/bluesky/akasammythepuppy.me");
if (!response.ok) throw new Error("Statistics unavailable");
const profile = await response.json();
const followers = profile.metrics.followers;
console.log(followers.value, followers.observedAt, followers.source);

Try this read-only request ↗ · OpenAPI JSON

2. Choose an endpoint

GET /v1/profiles/{platform}/{username}: Exact public lookup or an already published registered-owner snapshot.
GET /v1/history/{platform}/{username}?metric=followers&days=30: Recorded history for registered profiles. Ranges: 7 days (hourly), 30, 90, 365 days (daily). Empty history does not mean zero growth.
GET /v1/platforms: Implementation status and collection method. Self-service connections and events are not implemented.

Private analytics, writes and OAuth enrollment are not part of this public beta. YouTube is disabled here pending its separate redistribution and storage review.

3. Handle the states honestly

value: null: unavailable, not zero.
status: stale or current: false: retain the date; do not describe it as live.
precision: rounded: preserve the provider’s precision.
scope and sampleSize: distinguish lifetime totals, recent-post samples and reporting windows.

HTTP 400: invalid input. 403: provider not enabled. 404: unknown route. 405: unsupported method. 429: wait for Retry-After. 503: source temporarily unavailable. Avoid tight retry loops.

Reads are limited to 60 per minute per IP at a Cloudflare location; collector budgets also apply. GitHub and Bluesky lookups are cached for ten minutes. Twitch uses DecAPI and a five-minute cache. These intervals do not guarantee source freshness.

Do not combine different metric types, infer demographics, or label cross-platform totals as unique people. Public read access is not a blanket license to retain or redistribute every provider’s data.

4. Embed a display

Choose cards, graph, carousel or ticker in the explorer and copy its iframe. Motion starts paused and respects reduced-motion settings. History charts show actual dated observations; gaps remain gaps.

Build a Bluesky widget ↗

Keep provider tokens on your server, never in a widget URL. Public widgets contain only already-published data.

5. Recent content & observed changes

GET /v1/content/{platform}/{username}

Inspect the enrolled TikTok sample. This returns up to 20 public records, raw counters, source, observation time and sample coverage. Only enrolled accounts with a published sample have results; other searches return connection_required.

Sort the sample by a supplied raw counter or public interactions. Interactions sum the response’s interactionFields, not an official engagement rate. change compares the same post across two compatible observations within 24 hours. Missing change is not zero growth; these are observed gains, not platform-wide trending rankings.