SOCIALSCOPE
Opening your workspace…
Opening your workspace…
BUILD ON THE SIGNAL
Versioned endpoints, explicit data modes and inspectable methodology.
API V1
The API is served from the same origin as the application. Public analytics do not need a SocialScope session on a public deployment. Private hosted deployments also require the hosting platform’s authentication.
GET /api/v1/providers
GET /api/v1/search?platform=github&q=machine-learning
GET /api/v1/github/repository?q=vercel/next.js
GET /api/v1/trends?mode=DEMO&days=90Writes use JSON and require a matching Origin header. User-specific endpoints also require a valid signed-in session.
The MIT-licensed source includes setup instructions, migrations, tests and Docker configuration. Use Node.js 24 and pnpm 11.25.0.
pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm db:setup
pnpm devLocal development uses SQLite with a clearly labeled development identity. Production uses PostgreSQL and configured GitHub or Google OAuth. Keep provider API keys in server environment variables. See the repository README and docs/DEPLOYMENT.md for installation, backups and scheduling.
/providersMachine-readable capability manifests
/providers/statusRead or execute real health checks
/search?platform=github&q=…Bounded public discovery
/analyzeFetch, snapshot and calculate analytics
/analyze/streamNewline-delimited actual execution events
/trendsScores from stored or explicit demo data
/trends/:idOne scored public entity
/youtube/channel?q=@handleConfigured YouTube public analytics
/compareTwo to four analysis inputs
/watchlistOwner-scoped saved signals
/watchlist/:idOwner-scoped notes, folder or deletion
/foldersCreate an owner-scoped folder
/reportsSaved source-attributed reports
/reports/:id?format=htmlHTML, CSV or JSON report
/alertsConfigure numeric threshold alerts
/jobs/runAdmin session or cron bearer token
POST /api/v1/analyze
Content-Type: application/json
Origin: https://your-socialscope.example
{ "query": "vercel/next.js", "platform": "github", "mode": "LIVE" }
// Response envelope
{ "entity": { "mode": "LIVE", "fetchedAt": "…", "metrics": [] },
"trend": { "score": null, "confidence": 18.3 },
"events": [], "insights": [] }Only measured count history is used. Snapshots are deduplicated into ten-minute buckets. Two observations are required for velocity, three for acceleration. Scores compare an entity with its own history and are not a cross-platform popularity ranking.
Δ count ÷ elapsed daysΔ velocity ÷ elapsed midpoint days50 + 25 × tanh(relative daily growth % ÷ 3)positive intervals ÷ all intervals × 10050 + 25 × tanh(acceleration ÷ max(1, |velocity|))0.50 × momentum + 0.30 × persistence + 0.20 × acceleration componentWith only two samples, acceleration is unknown and its score component uses the neutral midpoint, 50. Confidence weights sample count (70%), observed time span (20%) and freshness (10%). It measures coverage, not statistical certainty or predictive accuracy.
Novelty is time since the first stored observation, not the age of the real-world topic. Breadth and diversity are one source per entity in v0.1.0. Sentiment is unavailable; missing sentiment is null.
Set secrets in your server environment, never in public client variables. GitHub and Hacker News work without API keys, subject to provider availability and rate limits.
GITHUB_TOKEN (optional)Public repository/profile reads. Tokens must be administrator-provided, least privilege.
YOUTUBE_API_KEYEnable YouTube Data API v3. Public channel totals and up to 12 uploads.
REDDIT_ACCESS_TOKEN + REDDIT_USER_AGENTRequires approved access; the administrator must refresh expired access tokens.
X_BEARER_TOKENRequires a compatible API plan; public profile metrics only.
No live account adapter in v0.1.0Use supported owner-export formats for local analysis.
Hosted SocialScope uses managed ChatGPT sign-in. Self-hosting supports Auth.js with GitHub or Google OAuth after configuring client IDs, secrets, callback URLs and AUTH_SECRET. Authentication tokens stay in secure cookies. Provider credentials stay on the server.
Authenticated endpoints enforce owner identity. Admin endpoints require a configured ADMIN_USER_IDS allowlist. Requests are rate-limited using durable database counters. Public fetching is restricted to fixed official API hostnames, with redirects rejected and response-size limits enforced.
User export files are processed locally with archive path, file-size, expansion and record-count limits. Report output escapes HTML and neutralizes spreadsheet formulas in CSV cells.
A response fetched less than one minute ago.
Less than one hour old.
One hour to one day old, or an old health check.
More than one day old. Shown with a warning.
No usable result or successful provider connection.
LIVE, CACHED and DEMO are distinct data modes. A cached result never becomes a live response. Demo observations use a fixed fictional dataset date. Public API data is cached for 5–15 minutes depending on the provider.
{ "error": {
"code": "PROVIDER_RATE_LIMIT",
"message": "The provider temporarily rate-limited this request.",
"provider": "github", "retryable": true, "retryAfter": 60
} }Default limits: 20 analyses and 90 ordinary API operations per minute per signed-in identity, or per trusted public address where available; 2 provider-health refreshes per minute. No pagination beyond the documented bounded samples is implied.