# Verosight

> Social media intelligence API. Access real-time data from X, Instagram, TikTok, Facebook, LinkedIn, YouTube, and news portals.

Verosight is a usage-based social media intelligence API built by Volantis. It provides programmatic access to crawled social media data including posts, comments, profiles, sentiment analysis, trending topics, and more.

## API

- Base URL: https://api.verosight.com
- Auth: API key (X-API-Key header) or JWT Bearer token
- Format: JSON REST API with cursor-based pagination
- Credits: Each call costs credits (free accounts get 1,000 credits)

## Key Endpoints

- GET /v1/posts — Search social media posts (2 credits). Supports exclude_profiles and exclude_keywords query params (comma-separated)
- GET /v1/comments — Search comments (2 credits). Supports exclude_profiles and exclude_keywords query params (comma-separated)
- GET /v1/profiles — Browse profiles (2 credits)
- GET /v1/profiles/:platform/:name — Get profile details, auto-crawls if missing (1 credit)
- GET /v1/analytics/trending — Trending posts and profiles (5 credits). Params: days, limit, platform, keyword (optional, filter by topic), exclude_profiles (comma-separated), exclude_keywords (comma-separated)
- GET /v1/analytics/sentiment?query= — Sentiment analysis (5 credits). Params: query, days, platform, exclude_profiles (comma-separated), exclude_keywords (comma-separated)
- GET /v1/analytics/topics — Trending topics/hashtags (5 credits). Params: days, limit, platform, keyword (optional, filter posts before clustering), exclude_profiles (comma-separated), exclude_keywords (comma-separated)
- GET /v1/analytics/compare?profiles= — Compare profiles (5 credits)

- GET /v1/analytics/engagement-ranking — Profiles by engagement (5 credits). Params: days, limit, platform, keyword (optional, filter by topic), exclude_profiles (comma-separated), exclude_keywords (comma-separated)
- GET /v1/analytics/experts?query= — Find topic experts by authority score (5 credits). Params: query, days, limit, platform, exclude_profiles (comma-separated), exclude_keywords (comma-separated)
- GET /v1/analytics/sentiment-trend — Daily sentiment trend (3 credits). Params: days, platform, keyword (optional — filter by topic using semantic search)
- GET /v1/analytics/hashtags — Trending hashtags by engagement (3 credits). Params: days, limit, platform, keyword (optional — find hashtags in topic-relevant posts)
- GET /v1/analytics/mentions — Most-mentioned profiles (3 credits). Params: days, limit, platform, keyword (optional — find mentions in topic-relevant posts)
- GET /v1/analytics/best-time — Best posting times by engagement heatmap (3 credits). Params: platform, profile_name, keyword (optional — analyze topic-specific posting times), days
- GET /v1/analytics/growth — Follower/following growth over time (3 credits). Params: platform (required), profile_name (required), days
- GET /v1/recommendations/:name — AI recommendations from social buzz (15 credits). Names: products, movies, books, software, games, travel, skills, content, marketing, problems. Params: query (topic), days, platform
- POST /v1/search — Semantic search (5 credits). Filters support exclude_profiles and exclude_keywords arrays
- POST /v1/chat — AI chat with tool-use, SSE streaming (20 credits). Body: { "message": "your question", "conversation_id": "optional-uuid" }. Omit conversation_id to start a new conversation. Returns SSE events: conversation_id (with new/existing ID), tool_status (running/done/error), content_block_delta (streaming text), done. Backend manages conversation context automatically. Chat tools support semantic search with optional engagement sorting (sort=engagement on search_posts).
- GET /v1/conversations — List chat conversations, newest first (free). Params: limit, offset
- GET /v1/conversations/:id — Get conversation with all messages (free)
- DELETE /v1/conversations/:id — Delete conversation (free)
- PATCH /v1/conversations/:id — Rename conversation (free). Body: { "title": "new title" }
- GET /v1/account/balance — Check credit balance (free)
- GET /v1/account/usage — Usage stats (free)
- POST /v1/auth/token — Exchange API key for JWT (free)

### Seeds & Crawl

- GET /v1/seeds — List monitored profiles (free)
- POST /v1/seeds — Add seed (free). Body: { "platform": "x", "profile_id": "username", "label": "", "post_limit": 50, "comment_limit": 100, "schedule_enabled": false, "schedule_interval_minutes": 1440 }. Platforms: x, instagram, tiktok, facebook, linkedin, youtube, news_portal. Returns 409 if already monitoring. Re-adding a deleted seed reactivates it.
- DELETE /v1/seeds/:id — Stop monitoring (soft delete, free). Data preserved.
- POST /v1/seeds/:id/crawl — Trigger crawl (10 credits). Returns queue position and estimated wait. Returns 409 if crawl already running.
- GET /v1/seeds/:id/jobs — Crawl history (1 credit)

## Supported Platforms

X (Twitter), Instagram, TikTok, Facebook, LinkedIn, YouTube, News Portals

Platform values are case-insensitive (e.g. "X" and "x" are equivalent).

## MCP Server

Verosight provides an MCP (Model Context Protocol) server for AI assistants like Claude and Cursor. Install via:

### Remote SSE (Recommended — no install)

SSE Endpoint: https://api.verosight.com/v1/mcp/sse
Auth: X-API-Key header with your API key

Cursor/Windsurf config:
```json
{
  "mcpServers": {
    "verosight": {
      "url": "https://api.verosight.com/v1/mcp/sse",
      "headers": { "X-API-Key": "vlt_live_YOUR_KEY" }
    }
  }
}
```

### Local Binary (stdio — for Claude Desktop)

Install: `curl -fsSL https://verosight.com/download/mcp/install.sh | sh`

Claude Desktop config:
```json
{
  "mcpServers": {
    "verosight": {
      "command": "verosight-mcp",
      "env": { "VEROSIGHT_API_KEY": "vlt_live_YOUR_KEY" }
    }
  }
}
```

Available MCP tools (19): search_posts, get_post, search_comments, list_profiles, get_profile, get_profile_stats, get_trending, analyze_sentiment, get_volume, get_topics, compare_profiles, find_experts, get_sentiment_trend, get_hashtag_trending, get_mention_ranking, get_best_time, get_growth, semantic_search, get_balance

## Links

- Homepage: https://verosight.com
- API Docs: https://verosight.com/docs
- API Platform: https://verosight.com/api-platform
- Analytics Platform: https://verosight.com/analytics-platform
- Release Notes: https://verosight.com/release-notes
- Status: https://verosight.com/status
- Contact: https://verosight.com/contact
- Privacy: https://verosight.com/privacy
- Terms: https://verosight.com/terms