# ReelsRadar

> Track TikTok, Instagram Reels and YouTube Shorts by URL. Spot viral outliers in one dashboard.

ReelsRadar tracks public short-form video metrics for TikTok, Instagram Reels, YouTube Shorts and Facebook. Paste a URL — no social OAuth. Spot viral outliers vs each account's own median.

## Agent endpoints

- [Developer documentation](https://reelsradar.io/docs): Architecture, tracking, API, and AI agent references
- [Getting started](https://reelsradar.io/docs/getting-started): First tracked URL
- [REST API](https://reelsradar.io/docs/api-introduction): JSON API conventions
- [OpenAPI 3.1](https://reelsradar.io/openapi.json): Machine-readable REST schema
- [Full LLM documentation](https://reelsradar.io/llms-full.txt): Expanded agent-oriented documentation
- [MCP introduction](https://reelsradar.io/docs/mcp-introduction): Planned Model Context Protocol surface
- [CLI introduction](https://reelsradar.io/docs/cli-introduction): Planned terminal agent workflow
- [AI crawlers](https://reelsradar.io/crawlers): Answer bots, indexers, and training crawlers

## Capability groups

- track: track URL, bulk track, scrape job status
- videos: list, filter, sort, viral multiplier, engagement rate
- accounts: list, pause, remove, analytics, posting activity
- collections: create, attach accounts/videos, filter dashboard
- overview: KPI cards, time series, virality & duration analysis
- export: CSV for videos or accounts
- alerts: viral threshold email rules
- billing: Stripe checkout, portal, founding yearly

## Docs index

### Get started

- [Getting started](https://reelsradar.io/docs/getting-started) · [markdown](https://reelsradar.io/docs/getting-started.md)
- [Core concepts](https://reelsradar.io/docs/concepts) · [markdown](https://reelsradar.io/docs/concepts.md)
- [Track accounts & videos](https://reelsradar.io/docs/tracking) · [markdown](https://reelsradar.io/docs/tracking.md)
- [Viral score](https://reelsradar.io/docs/viral-score) · [markdown](https://reelsradar.io/docs/viral-score.md)

### API

- [API introduction](https://reelsradar.io/docs/api-introduction) · [markdown](https://reelsradar.io/docs/api-introduction.md)
- [Authentication](https://reelsradar.io/docs/api-authentication) · [markdown](https://reelsradar.io/docs/api-authentication.md)
- [Track endpoint](https://reelsradar.io/docs/api-track) · [markdown](https://reelsradar.io/docs/api-track.md)
- [Videos endpoint](https://reelsradar.io/docs/api-videos) · [markdown](https://reelsradar.io/docs/api-videos.md)
- [Accounts endpoint](https://reelsradar.io/docs/api-accounts) · [markdown](https://reelsradar.io/docs/api-accounts.md)
- [Export endpoint](https://reelsradar.io/docs/api-export) · [markdown](https://reelsradar.io/docs/api-export.md)
- [Webhooks](https://reelsradar.io/docs/webhooks) · [markdown](https://reelsradar.io/docs/webhooks.md)

### AI agents

- [llms.txt](https://reelsradar.io/docs/llms) · [markdown](https://reelsradar.io/docs/llms.md)
- [OpenAPI](https://reelsradar.io/docs/openapi) · [markdown](https://reelsradar.io/docs/openapi.md)
- [MCP introduction](https://reelsradar.io/docs/mcp-introduction) · [markdown](https://reelsradar.io/docs/mcp-introduction.md)
- [CLI introduction](https://reelsradar.io/docs/cli-introduction) · [markdown](https://reelsradar.io/docs/cli-introduction.md)
- [Agent guidance](https://reelsradar.io/docs/agent-guidance) · [markdown](https://reelsradar.io/docs/agent-guidance.md)

### Product

- [Collections](https://reelsradar.io/docs/collections) · [markdown](https://reelsradar.io/docs/collections.md)
- [Filters & export](https://reelsradar.io/docs/filters-export) · [markdown](https://reelsradar.io/docs/filters-export.md)
- [Plans & limits](https://reelsradar.io/docs/plans-limits) · [markdown](https://reelsradar.io/docs/plans-limits.md)
- [AI crawlers](https://reelsradar.io/docs/crawlers) · [markdown](https://reelsradar.io/docs/crawlers.md)

## Programmatic SEO landings

- [TikTok analytics for any public account](https://reelsradar.io/tiktok-track/analyze-account)
- [Instagram Reels analytics by URL](https://reelsradar.io/instagram-track/analyze-reels-account)
- [YouTube Shorts tracking](https://reelsradar.io/youtube-track/analyze-channel)
- [Facebook video analytics by URL](https://reelsradar.io/facebook-track/analyze-account)

- Niche pages: 6 · Use-cases: 5 · Alternatives: 6 · Comparisons: 5
- Index: https://reelsradar.io/track

## Important constraints

- Dashboard REST routes authenticate with the Supabase session cookie from /login.
- Only public social metrics are collected. Users never connect TikTok/Instagram/YouTube OAuth.
- Video plan limits apply. Accounts are unlimited. Honor Retry-After and plan ceilings.
- Destructive operations (remove account, delete collection) require explicit user confirmation.
- Every human docs page has a `.md` twin for agents.


---

# Full documentation

## Getting started

Source: https://reelsradar.io/docs/getting-started.md

# Getting started

ReelsRadar tracks public short-form video metrics by URL. No social OAuth. Paste a profile or video link and metrics land in your dashboard.

## 1. Create an account

1. Open [https://reelsradar.io/signup](https://reelsradar.io/signup)
2. Sign up with Google or email
3. You get a 7-day trial with 50 tracked videos — no credit card

## 2. Track something

From **All Videos** or **All Accounts**, click **Track** and paste:

- A TikTok profile or video URL
- An Instagram Reels / profile URL
- A YouTube channel or Shorts URL
- A Facebook page or video URL

## 3. Read the dashboard

- **Overview** — KPI cards and growth charts
- **All Videos** — sortable grid/table with engagement rate and viral multipliers
- **All Accounts** — posting cadence, viral performance rate, totals
- **Collections** — group competitors or campaigns

## Next

- [Core concepts](https://reelsradar.io/docs/concepts)
- [Track accounts & videos](https://reelsradar.io/docs/tracking)
- [API introduction](https://reelsradar.io/docs/api-introduction)

---

## Core concepts

Source: https://reelsradar.io/docs/concepts.md

# Core concepts

## Workspace

Every user gets a workspace with a plan, video limit, seat limit, and refresh interval.

## Tracked account

A public social profile you monitor. ReelsRadar scrapes recent videos and stores metrics. Accounts themselves are unlimited; **videos** count toward your plan.

## Tracked video

A unique video stored in your workspace. Can come from an account scrape or from an individually pasted URL (`is_individual`).

## Viral multiplier

`latest_views / account_median_views`. A `128×` badge means the video outperformed that account's typical post by 128×.

## Refresh interval

How often due accounts are re-scraped (24h on Starter / trial, 12h on Pro).

## Collections

Named groups of accounts and videos used as dashboard filters.

---

## Track accounts & videos

Source: https://reelsradar.io/docs/tracking.md

# Track accounts & videos

## Single track

`POST /api/track` with JSON:

```json
{
  "url": "https://www.tiktok.com/@creator",
  "collection_id": "optional-uuid"
}
```

Returns `type: "account"` or `type: "video"` plus a `job_id` when a scrape is queued.

## Bulk track

`POST /api/track/bulk` with up to 50 URLs. Each line is processed independently.

## Status lifecycle

1. `pending` — scrape queued / running
2. `active` — metrics saved
3. `error` — private post, not a video, or scraper failure
4. `paused` / `removed` — account monitoring stopped

## Important

- Only **public** data is collected
- You never connect TikTok / Instagram / YouTube OAuth
- Failed individual videos show an error state in the table instead of disappearing

---

## Viral score

Source: https://reelsradar.io/docs/viral-score.md

# Viral score

ReelsRadar does not compare every creator to a global average. Each video is scored against **that account's median views**.

## Formula

```
viral_multiplier = latest_views / median_views_of_account
```

## Why it matters

A 200K-view post from a 5K-median creator is more interesting than a 200K post from a 180K-median creator. Outlier detection surfaces breakout content for agencies and competitive research.

## Where it appears

- Video cards and tables
- Overview "top viral" row
- Virality analysis histogram
- Optional email alerts when multiplier exceeds your threshold

---

## API introduction

Source: https://reelsradar.io/docs/api-introduction.md

# API introduction

Base URL: `https://reelsradar.io/api`

OpenAPI 3.1 schema: [https://reelsradar.io/openapi.json](https://reelsradar.io/openapi.json)

## Conventions

- JSON request and response bodies
- Session cookie auth for dashboard routes (same origin)
- Public routes: signup, lead capture, founding stats
- Machine routes: Stripe webhook, Apify webhook, cron (secret bearer)

## Capability groups

- **track** — paste URLs, start scrapes
- **videos** — list / filter tracked videos
- **accounts** — list / update / analytics
- **collections** — group items
- **overview** — KPI aggregates
- **export** — CSV download
- **billing** — Stripe checkout / portal
- **alerts** — viral threshold rules

## Agent surfaces

- [llms.txt](https://reelsradar.io/llms.txt) — compact agent index
- [llms-full.txt](https://reelsradar.io/llms-full.txt) — expanded docs
- [MCP introduction](https://reelsradar.io/docs/mcp-introduction)
- [CLI introduction](https://reelsradar.io/docs/cli-introduction)

---

## Authentication

Source: https://reelsradar.io/docs/api-authentication.md

# Authentication

## Dashboard session

Browser users authenticate with Supabase Auth (Google OAuth, magic link, or password). Dashboard API routes read the session cookie via `getAuthContext()`.

Unauthenticated calls receive `401`.

## Cron & webhooks

| Route | Auth |
| --- | --- |
| `POST /api/webhook/stripe` | Stripe signature header |
| `POST /api/webhooks/apify` | Job id query + Apify payload |
| `GET /api/cron/refresh` | `Authorization: Bearer CRON_SECRET` |
| `GET /api/cron/alerts` | `Authorization: Bearer CRON_SECRET` |

## Agent guidance

AI assistants must never ask users to paste secrets into chat. Prefer environment variables and the dashboard session.

---

## Track endpoint

Source: https://reelsradar.io/docs/api-track.md

# Track endpoint

`POST https://reelsradar.io/api/track`

## Request

```json
{
  "url": "https://www.instagram.com/reel/XXXX/",
  "collection_id": null
}
```

## Response (video)

```json
{
  "success": true,
  "type": "video",
  "video": { "id": "...", "status": "pending" },
  "job_id": "...",
  "message": "Tracking started. Metrics will appear in a few minutes."
}
```

## Errors

- `400` — missing / invalid URL
- `401` — not signed in
- `403` — no plan access or video limit reached

---

## Videos endpoint

Source: https://reelsradar.io/docs/api-videos.md

# Videos endpoint

`GET https://reelsradar.io/api/videos`

## Query params

| Param | Description |
| --- | --- |
| `platforms` | Comma list: tiktok,instagram,youtube,facebook |
| `datePreset` | allTime, last7, last30, custom |
| `dateFrom` / `dateTo` | ISO dates when custom |
| `collectionId` | Filter by collection |
| `individualOnly` | `1` for individually tracked posts |
| `tiktokShopOnly` | `1` for TikTok Shop posts |
| `sort` | JSON array of `{column,direction}` |
| `limit` | Default 50 |

## Response

```json
{
  "videos": [],
  "total": 0
}
```

---

## Accounts endpoint

Source: https://reelsradar.io/docs/api-accounts.md

# Accounts endpoint

## List

`GET https://reelsradar.io/api/accounts`

Returns accounts with `video_count`, `viral_performance_rate`, `posting_activity_7d`, totals.

## Update

`PATCH https://reelsradar.io/api/accounts/:id`

```json
{ "status": "paused", "tracking_limit": 30 }
```

## Analytics

`GET https://reelsradar.io/api/accounts/:id/analytics`

KPI series, duration buckets, and related videos for the account detail panel.

---

## Export endpoint

Source: https://reelsradar.io/docs/api-export.md

# Export endpoint

`GET https://reelsradar.io/api/export?type=videos`

Or `type=accounts`.

Accepts the same filter query string as the videos/accounts list endpoints. Returns `text/csv`.

---

## Webhooks

Source: https://reelsradar.io/docs/webhooks.md

# Webhooks

## Stripe

`POST /api/webhook/stripe`

Keeps workspace plan, video limit, and `hasAccess` in sync with Checkout and subscription events.

## Apify

`POST /api/webhooks/apify?job_id=...`

Receives actor run completion, fetches the dataset, normalizes metrics, writes `metric_snapshots`, and marks videos/accounts `active` or `error`.

---

## llms.txt

Source: https://reelsradar.io/docs/llms.md

# llms.txt

ReelsRadar publishes an [llms.txt](https://reelsradar.io/llms.txt) file so coding agents and LLM crawlers can discover the product surface quickly.

## Files

| URL | Purpose |
| --- | --- |
| [https://reelsradar.io/llms.txt](https://reelsradar.io/llms.txt) | Compact index of docs, API, and capabilities |
| [https://reelsradar.io/llms-full.txt](https://reelsradar.io/llms-full.txt) | Expanded agent-oriented documentation |
| [https://reelsradar.io/openapi.json](https://reelsradar.io/openapi.json) | Machine-readable REST schema |

## Convention

Every human docs page also has a markdown twin. Append `.md` to any `/docs/...` URL.

Example:

- Human: https://reelsradar.io/docs/getting-started
- Markdown: https://reelsradar.io/docs/getting-started.md

---

## OpenAPI

Source: https://reelsradar.io/docs/openapi.md

# OpenAPI

Machine-readable schema:

[https://reelsradar.io/openapi.json](https://reelsradar.io/openapi.json)

Use it to generate clients, feed MCP tooling, or ground coding agents.

Covered groups: track, videos, accounts, collections, overview, export, alerts, workspace, billing, public auth/lead endpoints, and webhook/cron machine routes (marked as such).

---

## MCP introduction

Source: https://reelsradar.io/docs/mcp-introduction.md

# MCP introduction

ReelsRadar is building an MCP server so assistants (Cursor, Claude, ChatGPT) can query tracked videos and start tracking jobs with natural language.

## Planned endpoint

```
https://reelsradar.io/api/mcp
```

Transport: Streamable HTTP. Auth: Bearer workspace token (dashboard-created).

## Planned tool groups

- `videos` — search, list, get metrics
- `accounts` — list, pause, analytics summary
- `track` — track URL / bulk track
- `collections` — list and attach items
- `overview` — KPI snapshot
- `export` — request CSV

## Safety rules

- Destructive tools require `confirm: true`
- Never ask users to paste secrets into chat
- Respect plan video limits and rate ceilings

## Status

MCP runtime is on the roadmap. Until it ships, agents should use:

1. [https://reelsradar.io/llms.txt](https://reelsradar.io/llms.txt)
2. [https://reelsradar.io/openapi.json](https://reelsradar.io/openapi.json)
3. Session-authenticated REST from the user's browser automation / local scripts

---

## CLI introduction

Source: https://reelsradar.io/docs/cli-introduction.md

# CLI introduction

A `reelsradar` CLI is planned for terminal-based agents.

## Planned install

```sh
npm install -g @reelsradar/cli
reelsradar login
```

## Planned commands

```sh
reelsradar whoami
reelsradar videos list --platform tiktok --limit 20
reelsradar track "https://www.tiktok.com/@creator"
reelsradar accounts list --json
reelsradar export videos --out videos.csv
```

Prefer `--json` when an agent needs structured output.

## Until the CLI ships

Use the REST API with a signed-in session cookie from local development, or drive the dashboard UI. Read [https://reelsradar.io/docs/api-introduction](https://reelsradar.io/docs/api-introduction) and [https://reelsradar.io/openapi.json](https://reelsradar.io/openapi.json).

---

## Agent guidance

Source: https://reelsradar.io/docs/agent-guidance.md

# Agent guidance

When helping a human with ReelsRadar:

1. Prefer docs `.md` pages and `llms.txt` for grounding
2. Prefer OpenAPI for endpoint shapes
3. Prefer MCP/CLI when available; otherwise REST
4. Do not delete accounts, collections, or billing objects unless the user explicitly asks
5. Do not expose API secrets, cron secrets, or `.env` values in chat
6. For tracking failures, check video `status` (`pending` / `error`) and Apify configuration
7. Remind users that only **public** social data is collected — no OAuth

## Useful links

- Docs: https://reelsradar.io/docs
- llms.txt: https://reelsradar.io/llms.txt
- OpenAPI: https://reelsradar.io/openapi.json
- Crawlers: https://reelsradar.io/crawlers
- Pricing: https://reelsradar.io/pricing

---

## Collections

Source: https://reelsradar.io/docs/collections.md

# Collections

Collections are named buckets of tracked accounts and videos.

## Use cases

- Competitor sets
- Client campaigns
- Niche research lists

## API

- `GET/POST /api/collections`
- `PATCH/DELETE /api/collections/:id`
- `GET/POST /api/collections/:id/items`

Filter the dashboard with `collectionId` on videos, accounts, overview, and export.

---

## Filters & export

Source: https://reelsradar.io/docs/filters-export.md

# Filters & export

## Filters

Dashboard filters live in the URL so views are shareable:

- Platforms
- Date range (all time / 7d / 30d / custom)
- Collection
- Individual videos only
- TikTok Shop only
- Multi-level sort
- Metric operators (views >, ER <, etc.)

## Export

From Advanced filters or Export menu:

`GET /api/export?type=videos` or `type=accounts`

The active filter query string is applied to the CSV.

---

## Plans & limits

Source: https://reelsradar.io/docs/plans-limits.md

# Plans & limits

| Plan | Videos | Seats | Refresh |
| --- | --- | --- | --- |
| Trial | 50 | 1 | 24h |
| Starter | 1,000 | 1 | 24h |
| Pro | 5,000 | 3 | 12h |
| Founding yearly | 1,000 | 1 | 24h |

Accounts are unlimited. Only unique tracked videos count.

See [https://reelsradar.io/pricing](https://reelsradar.io/pricing).

---

## AI crawlers

Source: https://reelsradar.io/docs/crawlers.md

# AI crawlers

ReelsRadar publishes public marketing, docs, and programmatic SEO pages so answer engines and search indexes can cite accurate product information.

Browse the human directory: [https://reelsradar.io/crawlers](https://reelsradar.io/crawlers)

## What we optimize for

- **Answer bots** (ChatGPT-User, Claude-User, Perplexity-User) — fresh docs and llms.txt
- **Search indexes** (Googlebot, OAI-SearchBot, Claude-SearchBot) — sitemap + semantic HTML
- **Training crawlers** — public product pages only; no private dashboard data

Private app routes (`/dashboard/*`, `/api/*`, auth) remain disallowed in robots.txt.

---

# Programmatic SEO path catalog

- https://reelsradar.io/track
- https://reelsradar.io/for
- https://reelsradar.io/alternatives
- https://reelsradar.io/compare
- https://reelsradar.io/track/tiktok/analyze-account
- https://reelsradar.io/track/tiktok/track-competitors
- https://reelsradar.io/track/tiktok/viral-videos
- https://reelsradar.io/track/tiktok/engagement-rate
- https://reelsradar.io/track/tiktok/bulk-import
- https://reelsradar.io/track/instagram/analyze-account
- https://reelsradar.io/track/instagram/track-competitors
- https://reelsradar.io/track/instagram/viral-videos
- https://reelsradar.io/track/instagram/engagement-rate
- https://reelsradar.io/track/instagram/bulk-import
- https://reelsradar.io/track/youtube/analyze-account
- https://reelsradar.io/track/youtube/track-competitors
- https://reelsradar.io/track/youtube/viral-videos
- https://reelsradar.io/track/youtube/engagement-rate
- https://reelsradar.io/track/youtube/bulk-import
- https://reelsradar.io/track/facebook/analyze-account
- https://reelsradar.io/track/facebook/track-competitors
- https://reelsradar.io/track/facebook/viral-videos
- https://reelsradar.io/track/facebook/engagement-rate
- https://reelsradar.io/track/facebook/bulk-import
- https://reelsradar.io/for/agencies/tiktok
- https://reelsradar.io/for/ecommerce-brands/tiktok
- https://reelsradar.io/for/creators/tiktok
- https://reelsradar.io/for/media-buyers/tiktok
- https://reelsradar.io/for/saas-marketers/tiktok
- https://reelsradar.io/for/ugc-managers/tiktok
- https://reelsradar.io/for/agencies/instagram
- https://reelsradar.io/for/ecommerce-brands/instagram
- https://reelsradar.io/for/creators/instagram
- https://reelsradar.io/for/media-buyers/instagram
- https://reelsradar.io/for/saas-marketers/instagram
- https://reelsradar.io/for/ugc-managers/instagram
- https://reelsradar.io/for/agencies/youtube
- https://reelsradar.io/for/ecommerce-brands/youtube
- https://reelsradar.io/for/creators/youtube
- https://reelsradar.io/for/media-buyers/youtube
- https://reelsradar.io/for/saas-marketers/youtube
- https://reelsradar.io/for/ugc-managers/youtube
- https://reelsradar.io/for/agencies/facebook
- https://reelsradar.io/for/ecommerce-brands/facebook
- https://reelsradar.io/for/creators/facebook
- https://reelsradar.io/for/media-buyers/facebook
- https://reelsradar.io/for/saas-marketers/facebook
- https://reelsradar.io/for/ugc-managers/facebook
- https://reelsradar.io/alternatives/shortimize
- https://reelsradar.io/alternatives/socialinsider
- https://reelsradar.io/alternatives/sprout-social
- https://reelsradar.io/alternatives/iconosquare
- https://reelsradar.io/alternatives/exolyt
- https://reelsradar.io/alternatives/pentos
- https://reelsradar.io/compare/reelsradar-vs-shortimize
- https://reelsradar.io/compare/reelsradar-vs-exolyt
- https://reelsradar.io/compare/reelsradar-vs-socialinsider
- https://reelsradar.io/compare/tiktok-vs-instagram
- https://reelsradar.io/compare/tiktok-vs-youtube