Get Started with the Viral Outliers API & MCP Server

Step 0: Try it without an account

Two endpoints are free and need no key at all: a live sample of the outlier feed, and the machine-readable price list.

curl https://viraloutliers.com/api/v1/trending
curl https://viraloutliers.com/api/v1/pricing

Step 1: Create a free account (or skip it)

Sign up here. A free account is enough to buy credits and use the full API. Subscriptions are optional and additionally include a monthly credit allowance (Basic: 250, Pro: 750, Agency: 3,000).

Shortcut for agents and one-off users: pay $15 for 1,500 credits and your key is shown right after checkout (an account is created for the email you pay with). That covers Steps 1 to 3 in one click. Any billable call made without a key returns HTTP 402 payment_required carrying that same link, so an agent can hand it to its user.

Step 2: Create an API key

Go to Settings → API Keys and create a key. It starts with so_live_ and is shown once, so store it immediately. You can revoke and rotate keys on the same page.

Step 3: Add credits

On the same API Keys tab, buy a one-time pack (1,500 credits for $15, 4,200 credits for $39, 12,000 credits for $99) or use a subscription's monthly allowance. 1 credit = $0.01. Billing is prepaid with a hard stop at zero: calls fail with a machine-readable insufficient_credits error instead of running up a bill.

Step 4: Make your first REST call

Search outliers in any niche (1 credit per call):

curl -X POST https://viraloutliers.com/api/v1/search/content \
  -H "Authorization: Bearer so_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "home workout", "platforms": ["tiktok"], "minOutlierScore": 5}'

Every billable response includes X-Credits-Charged and X-Credits-Balance headers, so you can track spend per call (useful when several of your own users share one key).

Prefer a terminal? The official CLI (viral-outliers on npm, Node 20+) has one command per skill, prints JSON, and can wait for async jobs:

npx viral-outliers login --key so_live_YOUR_KEY
npx viral-outliers search-outliers --query "home workout" --platforms tiktok --min-outlier-score 5

Step 5: Connect an AI agent via MCP

In Claude Code:

claude mcp add --transport http viral-outliers https://viraloutliers.com/api/mcp \
  --header "Authorization: Bearer so_live_YOUR_KEY"

In Claude.ai or ChatGPT, add a custom connector with the URL https://viraloutliers.com/api/mcp and the same key. The server is listed on the official MCP registry as com.viraloutliers/viral-outliers. The free trending tool works even before the key is added.

In Cursor, one click installs it, or add the server to ~/.cursor/mcp.json (globally) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "viral-outliers": {
      "url": "https://viraloutliers.com/api/mcp"
    }
  }
}

Add your key to that entry as "headers": { "Authorization": "Bearer so_live_YOUR_KEY" }. Without it the free tools still work and a billable tool answers with a payment link.

In OpenClaw (with your key in the VIRAL_OUTLIERS_API_KEY environment variable):

openclaw mcp add viral-outliers --url https://viraloutliers.com/api/mcp \
  --transport streamable-http \
  --header "Authorization=Bearer ${VIRAL_OUTLIERS_API_KEY}"

In Hermes Agent, add it to config.yaml (the variable is read from your .env):

mcp_servers:
  viral-outliers:
    url: "https://viraloutliers.com/api/mcp"
    headers:
      Authorization: "Bearer ${VIRAL_OUTLIERS_API_KEY}"

Both can also install the ready-made skill that teaches the agent this whole workflow:

openclaw skills install @MatsClaes2/viral-outliers   # OpenClaw (ClawHub)
hermes skills tap add Viral-Outliers/agent-skills   # Hermes, then: hermes skills install viral-outliers
npx skills add Viral-Outliers/agent-skills          # Claude Code, Cursor, Codex (Agent Skills standard)
npm i -g viral-outliers                             # official CLI for shell-native agents, docs at /docs/cli

The same skill is published for agent-skills discovery at /.well-known/skills/index.json.

Step 6: Run async work (crawls, transcripts, remixes)

Skills that do real work (crawl a profile, transcribe a video, remix a post) charge on queueing and return a jobRef. Poll GET /api/v1/jobs/{jobRef} (free) every 10 to 30 seconds, then fetch the result: transcripts and visual analyses land on GET /api/v1/posts/{postId}, crawled profiles become searchable. Jobs that fail refund your credits automatically.

Step 7: Go further

• The full skill table with per-skill docs lives at /docs; the REST contract at openapi.json; a machine-readable site summary at /llms.txt.
• On insufficient_credits (HTTP 402), agents can call create_topup_link (free) to get a payment link for the account owner. On payment_required (HTTP 402 because no key was sent), the body's error.payment.checkoutUrl buys a key without an account.
• Found a bug? report_issue (POST /api/v1/feedback) is free.