Developers

The growth data layer for SaaS.

Every public product on UserTrack is available as JSON, and every founder can let an AI agent add, connect and report on their SaaS through MCP. Same numbers, same rules, three interfaces.

Overview

One domain layer, three surfaces

Website

Public growth pages, leaderboards, trending, milestones and share cards. Numbers are synced every 4 hours from read-only data sources — never typed in.

Public API

Read-only JSON for everything that is public. No key needed; an API key raises the limit to 1,000 requests per day.

MCP

52 tools for Claude Code, Cursor, Codex, VS Code or any MCP client. Your agent creates the project, connects the data source (native Better Auth plugin included), verifies it and publishes.

The website, the API and the MCP server call the same project, integration and metrics functions in the backend. Nothing is duplicated, so an agent and a founder see exactly the same data.

Quickstart

Set up with AI in 60 seconds

Generate an MCP token

Sign in and open /app/developer. Create an MCP token; it starts with ut_mcp_ and is shown once. Keep the default scopes for onboarding.

Add UserTrack MCP to your agent

claude mcp add --transport http usertrack https://usertrack-production.up.railway.app/mcp --header "Authorization: Bearer ut_mcp_…"

Run inside your SaaS repository, then start claude.

Open your SaaS repository

Start the agent inside the repository of the product you want to track. It will detect your auth stack from package.json and env files.

Tell your agent

Prompt

Add this project to UserTrack. Detect the current authentication/user stack, choose the safest supported UserTrack integration, configure it, verify it, and return the public UserTrack URL.

Also available as the MCP prompt add_project_to_usertrack. The agent asks you for any credential it cannot find in the repo.

Done

The agent hands you the public URL, e.g. https://usertrack-production.up.railway.app/s/your-slug. The first sync lands within seconds; the page updates every 4 hours from then on.

Public API v1

Read-only JSON for everything public

Base URL

https://usertrack-production.up.railway.app/api/v1

JSON, UTF-8, ISO 8601 timestamps. CORS enabled for browsers. Only additive changes within v1.

Authentication

Optional. Create an API key at /app/developer (prefix ut_api_, shown once) and send it as Authorization: Bearer or X-API-Key.

Endpoint

Query params

Returns

GET /saas/{slug}

—

Full public profile: metrics, trust, ranks, owner, URLs and the 8 latest milestones.

GET /saas/{slug}/metrics

—

Compact metrics view for badges, widgets and newsletters.

GET /saas/{slug}/history

range = 24h · 7d · 30d · 90d · 1y · all (default 30d)

Time series of total, new, activated (and, when published, visitors / converted) users with storage-aware resolution and explicit gaps.

GET /saas/{slug}/rank-history

kind = leaderboard · trending · window · days (7–730, default 90)

Stored daily leaderboard / trending positions, plus current, best and 7-days-ago position.

GET /saas/{slug}/benchmark-history

weeks (4–52, default 26)

Weekly benchmark standings, top-quarter positions only; 404 when the owner does not publish benchmarks.

GET /saas/{slug}/milestones

—

The 8 most recent milestones, newest first.

GET /saas/{slug}/funnel

timeframe = 7d · 30d · 90d (default 30d)

Lifecycle funnel Reached → Signed up → Activated → Trial → Converted: only published stages, rates, per-stage provenance and freshness.

GET /saas/{slug}/engagement

—

Activated users, activation rate and retention when published.

GET /saas/{slug}/conversion

—

Converted users and Signup / Activated / Trial → Converted rates when published. Never amounts.

GET /saas/{slug}/cohorts

—

Monthly signup cohorts traced through the lifecycle from pseudonymous identities, with identity quality.

GET /saas/{slug}/benchmarks

—

Public benchmark statement (top-quarter positions only).

GET /discover

category · limit

Discovery sections (trending, fastest today / week / month, new & rising, recently verified, biggest movers, hidden gems, mobile) and the activity feed, narrowed by category.

GET /compare

s = slug,slug · days = 7 · 30 · 90 · 365 · all

Compare 2–4 products: absolute and indexed daily series.

GET /leaderboard

board · window · category · size · platform · verified · limit (1–100, default 50)

Any board with the same filters as the website; rows carry position and movement (movers: the stored 7-day climb).

GET /trending

same as /leaderboard

Alias for /leaderboard?board=trending.

GET /categories

—

Categories that have at least one public product, with counts.

GET /datasets/{name}

trending · fastest-growing · new-and-rising · hidden-gems · movers; window · category · platform · limit · cursor · format = json · csv

Public datasets as JSON or CSV download (≤ 100 rows per window, cursor paging, methodology link in meta).

GET /datasets/categories/{slug}

board (default most-new) + the dataset params

One category as a dataset.

GET /datasets/rankings/history

period = YYYY-MM · board · category · format

Frozen monthly rankings; without period, the index of available periods.

GET /following

days (1–90) · limit (1–200) — API key required

Your watchlist: followed products with 7-day movement, followed founders and your personal feed. Private to the key owner, never public.

GET /users/{username}

—

Public founder profile with links and their public SaaS projects.

GET /users/{username}/history

range = 7d · 30d · 90d · 1y · all

Aggregate user growth across the founder's public projects.

Download: trending (JSON / CSV) · fastest-growing (JSON / CSV) · new-and-rising (JSON / CSV) · hidden-gems (JSON / CSV) · movers (JSON / CSV)

Leaderboard values: board = trending · fastest · most-users · most-new · most-activated · activation-rate · new-rising · hidden-gems · movers · best-conversion · best-trial-conversion · converted-growth; window = 24h · 7d · 30d; size = 0-100 · 100-1k · 1k-10k · 10k-100k · 100k+; platform = web · mobile · hybrid; verified = true (default) · false. Datasets share the API rate-limit buckets (CSV included) and are capped at 100 rows per window.

curl

curl https://usertrack-production.up.railway.app/api/v1/saas/acme/metrics

# with an API key
curl -H "Authorization: Bearer ut_api_…" \
  "https://usertrack-production.up.railway.app/api/v1/leaderboard?board=trending&window=7d&limit=10"

JavaScript

const res = await fetch("https://usertrack-production.up.railway.app/api/v1/saas/acme/metrics", {
  headers: { Authorization: `Bearer ${process.env.USERTRACK_API_KEY}` },
});
const { data, meta } = await res.json();
console.log(data.metrics.totalUsers, meta.generatedAt);

Example response · GET /saas/{slug}/metrics

{
  "data": {
    "slug": "acme",
    "name": "Acme",
    "verification": "verified",
    "metrics": {
      "totalUsers": 12481,
      "newUsers24h": 41,
      "newUsers7d": 312,
      "newUsers30d": 1922,
      "growth7dPercentage": 2.6,
      "growth30dPercentage": 18.2,
      "activatedUsers": 4870,
      "activationRatePercentage": 39,
      "trendingRank": 9,
      "overallRank": 4
    },
    "updatedAt": "2026-09-02T08:00:00.000Z",
    "urls": {
      "page": "https://usertrack-production.up.railway.app/s/acme",
      "badge": "https://usertrack-production.up.railway.app/api/badge/acme.svg"
    }
  },
  "meta": { "version": "v1", "generatedAt": "2026-09-02T10:15:00.000Z" }
}

Errors

{ "error": { "code": "not_found", "message": "…" } }

400

bad_request

Invalid query parameter; the message lists accepted values.

401

unauthorized

Key has the wrong format or does not exist — or /following was called without a key.

401

revoked

Key was revoked in the dashboard.

401

expired

Key passed its expiry date.

403

forbidden

Token is missing the required scope (MCP only).

404

not_found

Unknown slug or username, or the product is private.

429

rate_limited

Limit exceeded; wait for Retry-After seconds.

500

internal

Unexpected error on our side.

Rate limits

Anonymous

API key

Limit

60 req/min per IP

1,000 req/day per key

Burst

—

120 req/min

Caching

5 min, shared

none (private)

Window header

minute

day + X-RateLimit-Reset

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window; 429s add Retry-After.

OpenAPI

Machine-readable OpenAPI 3.1 at https://usertrack-production.up.railway.app/api/openapi.json. Generated from the same code as the routes, so it cannot drift.

Badge embed

<a href="https://usertrack-production.up.railway.app/s/your-slug">
  <img src="https://usertrack-production.up.railway.app/api/badge/your-slug.svg?type=users" alt="Your SaaS on UserTrack" height="28">
</a>

type = users · growth · trending · verified; theme = dark · light. Not rate limited, cached at the edge.

MCP

Let your agent do the setup

Endpoint

https://usertrack-production.up.railway.app/mcp

Streamable HTTP, stateless, JSON responses. POST JSON-RPC; GET returns a discovery document.

Auth header

Authorization: Bearer ut_mcp_…

MCP tokens only. Public API keys (ut_api_) are rejected with 401.

Scopes

projects:read

Read projects

List and inspect your SaaS projects, integration state and verification.

projects:write

Create & update projects

Create projects, edit metadata, publish. Never deletes.

integrations:read

Read integrations

Supported providers and setup instructions.

integrations:write

Configure integrations

Connect data sources, verify connections, trigger syncs.

metrics:read

Read metrics

Growth metrics, history, ranks, milestones and share URLs.

profile:read

Read profile

Your founder profile and account summary.

profile:write

Update profile

Edit your founder profile (name, bio, links, X handle) and create share cards from your events.

follows:read

Read your watchlist

Products and founders you follow, with their movement and the personal feed.

follows:write

Follow / unfollow products and founders

Add or remove products and founders on your watchlist.

webhooks:read

List webhook endpoints and deliveries

Your webhook endpoints (secrets masked), the event catalog and the delivery log.

webhooks:write

Create, update, test and rotate webhook endpoints

Manage webhook endpoints; new secrets are returned once.

Recommended: all 11 for onboarding (the default). For reporting-only agents, projects:read + metrics:read is enough; add follows:* for the watchlist and webhooks:* to manage webhook endpoints.

Tools (52)

Tool

Scope

Mode

What it does

usertrack_get_account

profile:read

read

Current UserTrack account: founder profile, token scopes and a short list of owned projects. Call this first to orient yourself.

usertrack_get_projects

projects:read

read

All SaaS projects owned by this account with metrics, verification and public URLs.

usertrack_get_project

projects:read

read

One project in full: metadata, integration state per role, verification, current metrics, URLs and the recommended next setup step.

usertrack_create_project

projects:write

write

Create a SaaS project. Idempotent: if this account already has a project for the same domain, the existing one is returned (created: false) instead of a duplicate. Returns the recommended integration for the detected stack.

usertrack_update_project

projects:write

write

Safe metadata changes: name, description, website, category, tags, logo, slug, publishing (isPublic) and the product profile (markets, tech stack, marketing channels, cofounders, country, funding, team size, founded month, value proposition, problem, audience, pricing model, anonymous mode, hide from search engines). Descriptive only — there are no revenue fields. Never deletes.

usertrack_import_from_trustmrr

projects:write

write

Prefill a product profile from its TrustMRR startup page: name, description, website, logo, category, markets, tech stack, marketing channels, cofounders, country, funding, team size, founded month, value proposition, problem, audience, pricing model. Revenue, MRR, prices and growth figures are never read or returned. Without a project ref it only returns { prefill, unmapped, source }; with projectId/slug and apply: true it fills the project's empty fields (overwrite: true replaces them) through the same update path as usertrack_update_project and links the TrustMRR slug. Uses the deployment's operator key — `not_configured` when none is set; 5 imports per founder per 10 minutes.

usertrack_get_supported_integrations

integrations:read

read

Catalog of supported data sources (native SDK for Better Auth / Prisma / Drizzle / Convex / Auth.js / custom apps, Supabase, Clerk, Firebase, Auth0, PostgreSQL read-only, PostHog, Plausible, GA4, Stripe, RevenueCat, Paddle, Lemon Squeezy, Chargebee, JSON endpoint, manual) with roles (users | activation | traffic | conversion), trust level, required credentials and what is read. Any credential handed over is stored AES-256-GCM encrypted and never returned. Pass what you detected to get a lifecycle recommendation.

usertrack_get_integration_setup

integrations:read

read

Structured, executable setup instructions for one provider: requirements, least-privilege permissions, ordered steps, code templates, security rules, the exact configure call and the verification call. Follow it step by step.

usertrack_configure_integration

integrations:write

write

Store a data-source configuration for a project and start the first sync. Credentials are validated, encrypted with AES-256-GCM before they reach the database and decrypted only inside the server process for a provider read — they are never returned to the dashboard, the API or an agent, and are unreadable in a database dump. Re-running replaces the source for that role (idempotent).

usertrack_verify_integration

integrations:write

write

Live connection test. Uses the stored config, or pass provider+config to test before saving. Returns connected/failed, detected user count, verification level and an actionable error. Cooldown: 20s per project.

usertrack_sync_project

integrations:write

write

Trigger an immediate sync of the project's data sources (60s cooldown per source). Results land within seconds.

usertrack_get_metrics

metrics:read

read

Growth summary for one project: total users, new users in the window vs the previous window, growth %, activation, retention, leaderboard/trending ranks with movement, recent milestones.

usertrack_get_growth_history

metrics:read

read

Graph-ready time series (totalUsers, newUsers, activatedUsers, visitors) for a range.

usertrack_get_rank

metrics:read

read

Current leaderboard and trending positions, previous positions, best rank, and whether the project is eligible (and why not).

usertrack_get_milestones

metrics:read

read

Achieved milestones (user counts, best day, top-10, streaks) with share page and share image URLs — everything needed to write a launch post.

usertrack_get_share_url

metrics:read

read

Public project page, founder profile, badge, OG image, share cards per metric and recent milestone shares.

usertrack_get_provider_recommendation

integrations:read

read

Given what you detected in the repo (packages, env vars, framework, project type), returns the lifecycle composition: the users source in priority order (Better Auth via the official @usertrack/better-auth plugin, then Supabase, Clerk, Firebase, Auth0, PostgreSQL, then the universal JSON endpoint) plus optional activation, traffic and conversion sources, with reasoning, detected auth methods and the stages that will be available. Mobile example: Firebase Auth + Sign in with Apple + PostHog + RevenueCat → Signed up: Firebase, Activated: PostHog, Trial/Converted: RevenueCat (Sign in with Apple is an auth method, never the users source). Call before creating or configuring.

usertrack_get_activation_setup

integrations:read

read

How to track activated users (the first meaningful value in the product) for a project: definition, example events, a ranking of your candidateEvents (outcome events such as first_*, *_created, *_completed, onboarding_completed win; $pageview, app_open, session_start, login, signup, $identify, click, screen_view are rejected with a reason), the recommended source given the detected stack (PostHog event, Supabase/Postgres table or SQL, endpoint) and the exact next calls. Optional step after the users source works.

usertrack_get_funnel

metrics:read

read

Lifecycle funnel Reached → Signed up → Activated → Trial → Converted for one project over 7d / 30d / 90d: per-stage counts, conversion from the previous stage, previous-window comparison, strategic rates (Signup → Converted, Activated → Converted, Trial → Converted), per-stage provenance, freshness and health. basis is 'aggregate' (period ratios); identityQuality (aggregate_only | partially_mapped | cohort_verified) says whether the same users can be traced across stages — use usertrack_get_cohorts for the cohort view. Only stages with a connected source are returned; missingStages + hint say what to connect next.

usertrack_get_trending

metrics:read

read

The public trending board (24h / 7d / 30d, optional category) with scores, ranks, movement and a one-line explanation per product; pass a project to also get its own position and score factors.

usertrack_get_benchmark

metrics:read

read

Where the project stands against cohorts (all SaaS, its category, products its size): percentile, median, p10–p90 range, multiple of the median and a plain-language insight per metric. Cohorts below the minimum size are omitted.

usertrack_compare_projects

metrics:read

read

Compare 2–4 public products (any slugs, not only your own) over 7 / 30 / 90 / 365 days or all history: current metrics, window growth and daily series in absolute and indexed (100 at start) form, plus the shareable /compare URL.

usertrack_get_share_card

metrics:read

read

Share page + image URLs (1200×630 and 1080×1080) for a card kind — users, growth (30d), week (7d), rank, trending, activation, milestone-<id> — plus an X intent link. Everything needed to post growth on social.

usertrack_get_embed_code

metrics:read

read

Copy-paste embed code. format 'widget' (recommended for websites): a live iframe widget via one <script> tag (types: users = live user count, growth = growth %, verified = Verified by UserTrack, chart = mini chart; theme auto/dark/light; 7d/30d) that refreshes every 5 minutes and links back to the growth page. format 'badge' (default, for READMEs): static SVG HTML/Markdown (types: users, growth, trending, verified, chart; dark/light; compact). Public metrics only, no API key involved.

usertrack_get_conversion_setup

integrations:read

read

How to add the Trial and Converted stages from a payment provider (Stripe, RevenueCat, Paddle, Lemon Squeezy, Chargebee or a JSON endpoint): the recommended definition of 'converted' (active_paid default, ever_paid, first_payment), least-privilege read-only credential, identity matching (metadata.userId / app_user_id / custom_data.userId), privacy rules and the exact configure + verify calls with role 'conversion'. Payment providers are read for conversion state only — never amounts, prices, invoices or MRR. Optional; private by default.

usertrack_get_identity_mapping

integrations:read

read

How to carry one stable user id across the identity source (Firebase uid, Supabase auth id, Clerk userId…), the analytics source (posthog.identify) and the conversion source (Stripe metadata.userId, RevenueCat app_user_id, Paddle custom_data.userId, Chargebee meta_data.userId) so UserTrack can trace signup cohorts to activation and conversion. Explains how ids are salted + hashed, the identity quality levels and the Cohort Verified thresholds. Never send emails, names or phone numbers.

usertrack_get_funnel_history

metrics:read

read

Daily history of the strategic rates (Signup → Activated, Signup → Converted, Activated → Converted, Trial → Converted) as trailing-7-day ratios for 14–365 days. Graph-ready.

usertrack_get_cohorts

metrics:read

read

Monthly signup cohorts traced through the lifecycle from pseudonymous identities: signed up, activated (+ D7), trial, converted (+ D30), rates, median time to activation / conversion, plus identityQuality, coverage and an explanation. Empty until sources report identities (see usertrack_get_identity_mapping).

usertrack_get_native_setup

integrations:read

read

Structured install plan for a native UserTrack source — the app itself answers signed aggregate requests (verified, no credentials shared). source: better-auth (official plugin @usertrack/better-auth: append userTrack() to the existing plugins array), prisma / drizzle / convex / authjs / custom (@usertrack/node: one route file exporting createUserTrackHandler with a count source; optional activation and conversion sources; optional push hook). Returns the install command for your package manager, the exact files to add (route, optional push hook, .env.example), env vars USERTRACK_PROJECT_ID / USERTRACK_SECRET, code-modification safety rules, what is sent (aggregate counts, no PII), steps and the verify call. Pass the project to get its state; the secret itself only comes from usertrack_create_integration.

usertrack_get_better_auth_setup

integrations:read

read

Deprecated alias of usertrack_get_native_setup { source: "better-auth" }: install plan for the official UserTrack plugin for Better Auth (@usertrack/better-auth). Prefer usertrack_get_native_setup.

usertrack_create_integration

integrations:write

write

Create the native SDK integration for a project and receive its credential: USERTRACK_PROJECT_ID and the USERTRACK_SECRET (ut_int_…). The secret is returned ONLY in this response — put it into the app's environment immediately, never print, log or commit it. UserTrack keeps its own copy AES-256-GCM encrypted and can never show it again. Idempotent: an existing integration is returned without a secret (secret: null); pass rotate: true to issue a new secret (the old one stops working). Then install the package (usertrack_get_native_setup), deploy and call usertrack_verify_integration. Activation and conversion roles reported by the same handler are attached automatically after the first sync.

usertrack_get_profile

profile:read

read

The founder's public profile (name, username, bio, links, X handle + connection state, xFollowers from the connected X account, location, visibility), founder-level aggregates across public projects (total users, new users 30d, weighted activation rate, best rank, trending count, biggest-growth project — formulas included), the public project list and the profile / card / API URLs.

usertrack_export_account

profile:read

read

GDPR Art. 20 export of everything UserTrack stores about this account as one JSON document: account, founder profile, projects with settings, integrations (public configuration only — never credentials), milestones, follows, webhook endpoints (secrets masked), developer tokens (masked), email preferences, X connection summary. Same document as the 'Download my data' button in Settings. Deleting the account is deliberately not available through MCP.

usertrack_update_profile

profile:write

write

Edit the founder profile: displayName, bio (≤160), website (https), x (accepts '@name', 'name' or an x.com URL — stored canonically as 'name'), github, linkedin, location, avatarUrl (https), profilePublic. Only the fields you pass change. Never touches tokens or the username.

usertrack_get_share_events

metrics:read

read

Share-ready events for this account (optionally one project): significant milestones, records, rank achievements, spikes and top-10% benchmarks that UserTrack turned into cards automatically. Each comes with score (strongest first), card URLs (page, 1200×630 image, 1080×1080 square) and an X draft + intent link. Use `strongest` to answer 'my best milestone this month'.

usertrack_create_share_card

profile:write

write

Build a share card configuration and get its deterministic PNG URLs: pass a project + kind (users, growth, week, rank, trending, activation, conversion, benchmark, milestone-<id>, spike-<id>) or a shareEventId, plus optional style (blueprint | aurora | minimal), size (og | square), range (7d | 30d | 90d | 1y | all, for the chart), chart / logo / founder / verified / dates toggles and a short custom title. Returns page, image and square URLs, the X draft and the verification wording. Referencing a share event marks it as shared.

usertrack_get_x_draft

metrics:read

read

A concise, data-driven X post for a share event or a card kind (users, growth, week, rank, trending, activation), with the share URL and a ready x.com intent link. Wording rotates per event and only says 'verified' for verified sources.

usertrack_get_founder_url

profile:read

read

Public founder profile URL (/u/<username>), the founder card PNG, the OG image and the public API endpoints for the profile and its aggregate history.

usertrack_discover

metrics:read

read

Public discovery sections in one call — trending, fastest growing, new & rising, hidden gems, biggest movers (7-day leaderboard climbs) and mobile — plus the activity feed and the public hidden-gem / new-rising rules. Optional category and window. Public data, not owner-scoped; requires metrics:read.

usertrack_follow_project

follows:write

write

Add a public product to the founder's watchlist by slug or project id. Idempotent: following an already-followed product returns created: false. Requires follows:write.

usertrack_unfollow_project

follows:write

write

Remove a product from the founder's watchlist by slug or project id. Safe to repeat (removed: false when it was not followed). Requires follows:write.

usertrack_follow_founder

follows:write

write

Follow a public founder by username (with or without @): every public project they publish lands on the watchlist and in the personal feed. Idempotent. Requires follows:write.

usertrack_unfollow_founder

follows:write

write

Stop following a founder by username. Safe to repeat. Requires follows:write.

usertrack_get_watchlist

follows:read

read

Everything the founder follows: products (direct follows plus public projects of followed founders) with 7-day leaderboard / trending movement, followed founders, and the personal feed (milestones, spikes, launches, verifications, rank jumps, benchmarks) for the last days. Requires follows:read.

usertrack_get_rank_history

metrics:read

read

Stored daily leaderboard or trending positions of one owned project (private projects included): one point per UTC day since the project was first ranked, plus current, best and 7-days-ago position with the 7-day movement. Graph-ready. Requires metrics:read.

usertrack_get_benchmark_history

metrics:read

read

Weekly benchmark standings of one owned project for the last weeks (private owner view: every cohort and metric, with value and median), plus the current cards' change insights ('Top 12% now, up from Top 27% last month'). Requires metrics:read.

usertrack_get_dataset

metrics:read

read

A public dataset as rows: trending, fastest-growing, new-and-rising, hidden-gems, movers, category (needs category; any board via board) or rankings (frozen monthly rankings: period YYYY-MM + optional board / category; without period, the list of available periods). Filters: window, category, platform (web | mobile | hybrid), limit (≤100). Returns the JSON and CSV URLs of the same dataset on the public API. Requires metrics:read.

usertrack_get_webhooks

webhooks:read

read

The founder's webhook endpoints (URL, subscribed events, project scope, status, masked secret, last delivery), the catalog of event types that can be subscribed to, the endpoint limit and the owned projects an endpoint can be scoped to. Secrets are never returned here. Requires webhooks:read.

usertrack_create_webhook

webhooks:write

write

Create a webhook endpoint: a public https URL, the event types to receive (milestone.reached, rank.changed, trending.rank_changed, growth.spike, integration.failed, integration.recovered, project.verified), an optional description and an optional project scope. The signing secret (whsec_…) is returned ONLY in this response — hand it to the founder for their environment, never print or log it. Then call usertrack_test_webhook. Requires webhooks:write.

usertrack_update_webhook

webhooks:write

write

Change an endpoint's URL, subscribed events, description, status (active | disabled — re-enabling resets the failure counter) or project scope (projectId, or null for all projects). Only the fields you pass change. Requires webhooks:write.

usertrack_test_webhook

webhooks:write

write

Send a signed webhook.test event through the normal delivery pipeline (signature headers, retries, delivery log) to one endpoint, regardless of its subscriptions. Returns the delivery id; check the result with usertrack_get_webhook_deliveries. Requires webhooks:write.

usertrack_get_webhook_deliveries

webhooks:read

read

Recent deliveries of one endpoint: event type, attempt, status (pending | success | failed | exhausted), HTTP status, latency, error and next retry time. failedOnly narrows to failed / exhausted deliveries. Response bodies are never stored. Requires webhooks:read.

Setup workflow

01usertrack_get_account
02usertrack_get_provider_recommendation (pass detectedProviders / detectedAuth / detectedAnalytics / detectedPayments + framework + projectType from the repo: native SDK (Better Auth plugin, or @usertrack/node for Auth.js / Convex / Prisma / Drizzle / custom) → Supabase → Clerk → Firebase → PostgreSQL → endpoint for users; Sign in with Apple / Google are auth methods, never the users source)
03usertrack_create_project (idempotent by domain)
04usertrack_get_integration_setup (recommended provider)
05native: usertrack_create_integration { provider: "native", source } → usertrack_get_native_setup { source } → install @usertrack/better-auth (add userTrack() to the existing plugins array) or @usertrack/node (add the route file with a count source; optionally activation / conversion sources), set USERTRACK_PROJECT_ID / USERTRACK_SECRET (never commit the secret), typecheck, deploy
06other providers: edit the repo only if the instructions say so (endpoint provider), then usertrack_configure_integration
07usertrack_verify_integration (wait ~5s, retry ≤3×)
08usertrack_update_project { isPublic: true }
09optional: usertrack_get_activation_setup → configure an activation source (PostHog event, Supabase/Postgres table) so the funnel shows activated users
10optional: usertrack_get_conversion_setup → configure a conversion source with role "conversion" (Stripe, RevenueCat, Paddle, Lemon Squeezy, Chargebee or endpoint) for Trial → Converted — payment providers are read for conversion state only, never revenue; private until the founder publishes it
11optional: usertrack_get_identity_mapping → carry one user id across sources so cohorts become Cohort Verified
12usertrack_get_share_url → hand the public URL to the founder

Sent to the agent as server instructions, so every client runs the same order without extra prompting.

Idempotency & limits

Daily quota

5,000 tool calls per token

Burst

120 tool calls per minute

Create project

≤ 10 per hour; same domain returns the existing project

Verify

20s cooldown per project

Sync now

60s cooldown per source

Configure

re-running replaces the source for that role

Reads are generous, writes are conservative. Rate-limit errors include retryAfterSec and a hint not to loop.

Security model

Tokens are stored as SHA-256 hashes and shown once. Revoke any time at /app/developer.
Every call re-checks the token, its scopes and that the project belongs to the token owner. Ids alone are never trusted.
No tool can delete a project or an integration.
Provider credentials are validated, stored server-side and never returned — not to the dashboard, not to the API, not to the agent.
Every write is recorded in an audit trail visible on the developer page.
Only aggregate counts ever leave your stack; no emails, names or per-user rows.

Troubleshooting

401

Missing, malformed, revoked or expired token, or a ut_api_ key used for MCP. Create a new MCP token and update the client config.

403

Token lacks the scope the tool needs (the error names it). Create a token with that scope.

429

Burst, daily quota, create limit or a cooldown. Wait retryAfterSec; do not retry in a loop.

404

Project not found or not owned by this token. Call usertrack_get_projects to list what the token can see.

Tool failures come back as tool results with isError: true and a structured error.code + hint, so agents can recover without parsing prose.

Webhooks

Get told when something happens

Signed POSTs to your https endpoint for milestone.reached, rank.changed, trending.rank_changed, growth.spike, integration.failed / recovered and project.verified.
Every payload carries UserTrack-Signature (HMAC-SHA256 with a per-endpoint secret shown once), a timestamp, a deterministic event id and an idempotency key; failed deliveries retry five times over 14 hours.
Manage endpoints in /app/developer, or let your agent do it with usertrack_create_webhook → usertrack_test_webhook → usertrack_get_webhook_deliveries.

Webhook reference: payloads, signatures, retries →

Examples

What to ask once connected

“How did my SaaS perform this week?”

Tools

usertrack_get_projects
usertrack_get_metrics { timeframe: "7d" }
usertrack_get_rank

New users vs the previous 7 days, growth %, activation, leaderboard and trending movement.

“Compare my projects.”

Tools

usertrack_get_projects
usertrack_get_metrics (per project)
usertrack_get_growth_history { range: "30d" }

A side-by-side table of totals, 30-day growth and ranks, plus a chart-ready series per project.

“Write a post about my biggest milestone.”

Tools

usertrack_get_milestones
usertrack_get_share_url

The milestone copy, its share page and OG image URL, ready to paste into X or LinkedIn.

“Follow the products I compete with and tell me what moved this week.”

Tools

usertrack_discover { category: "developer-tools" }
usertrack_follow_project { slug }
usertrack_get_watchlist { days: 7 }

Your watchlist with 7-day leaderboard and trending movement, plus the personal feed of milestones, spikes and rank jumps.

“Ping Slack when we hit a milestone.”

Tools

usertrack_get_webhooks
usertrack_create_webhook { url, events: ["milestone.reached"] }
usertrack_test_webhook

A signed endpoint, its secret handed to you once, and a test delivery you can inspect with usertrack_get_webhook_deliveries.

Get started

Create an API key or MCP token

Free. Takes ten seconds. Full references in docs/API.md and docs/MCP.md.

Open /app/developer