Vertical Viral

API Reference

The Vertical Viral API is a headless architecture designed to bypass detection entirely. It operates asynchronously: you submit a target, and we POST the structured JSON to your servers via a Webhook once the extraction is completely safe and finalized.

Authentication

All API requests must be authenticated using a Bearer token. Create your secret API key from the Developer Dashboard.

Never share your secret keys. Keep them vaulted. Do not commit them to GitHub or expose them in client-side code (e.g., React or Next.js public env vars).

Authorization Header
curl -X POST https://verticalviral.io/api/scrape/reelsanalyzer \
  -H "Authorization: Bearer vv_live_xt789..." \
  -H "Content-Type: application/json"

Instagram Reels Analyzer

Initiates an asynchronous stealth session on our proxy network.

POSThttps://verticalviral.io/api/scrape/reelsanalyzer

Request Body

target_usernamestring · required
The exact Instagram handle to analyze without the @ symbol. Example: nike
webhook_urlstring · required
The HTTPS endpoint on your server where we will POST the final JSON payload upon completion or failure. Must accept a JSON body.
depthinteger · optional
The number of Reels to scan. Defaults to 30. Maximum is 150. Deeper scans take longer to execute to maintain stealth.
cURL Example
curl -X POST https://verticalviral.io/api/scrape/reelsanalyzer \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "target_username": "mosbius",
    "webhook_url": "https://your-server.com/webhooks/vv",
    "depth": 50
  }'

Sync Response (200 OK)

The immediate response confirms the job was added to the stealth queue. You must store the job_id to correlate it when the webhook fires.

Response
{
  "status": "queued",
  "job_id": "job_8f2b3c4d5e",
  "message": "Extraction started. Data will be sent to your webhook."
}

Instagram Profile Scraper

Collects comprehensive target profile information (subscribers, business flag, public emails, and bio context).

POSThttps://verticalviral.io/api/scrape/profilescraper

Request Body

target_usernamestring · required
The exact Instagram handle to analyze without the @ symbol.
webhook_urlstring · required
The HTTPS endpoint on your server where we will POST the final JSON payload upon completion or failure. Must accept a JSON body.

Instagram Comment Scraper

Parses up to 500 top-level comments and replies directly from an Instagram Post URL.

POSThttps://verticalviral.io/api/scrape/commentscraper

Request Body

target_urlstring · required
The absolute URL of the Instagram Reel or Post to extract comments from.
webhook_urlstring · required
The HTTPS endpoint on your server where we will POST the final JSON payload upon completion or failure. Must accept a JSON body.

Webhook Delivery

Once the scrape finishes (typically 20-30 seconds), our servers will issue an HTTP POST to your provided webhook_url.

Payload Key Fields

status"completed" | "failed"
If failed, an error_message string will be included instead of the `data` block.
magnetism_scorefloat (0.0 - 10.0)
Our proprietary performance index for the specific Reel, based on view velocity and engagement ratios across the user's baseline.
outlier_statusboolean
Evaluates to true if the individual Reel performed 2x above the profile's calculated baseline average.
Webhook POST Body Example
{
  "id": "job_8f2b3c4d5e",
  "status": "completed",
  "target": "mosbius",
  "data": {
    "profile_stats": {
      "followers": 145200,
      "extracted_emails": ["hello@mosbius.com"]
    },
    "reels": [
      {
        "shortcode": "C9Z8A7X",
        "views": 1245000,
        "likes": 89000,
        "magnetism_score": 9.8,
        "outlier_status": true
      }
    ]
  }
}

Errors & Limits

Standard HTTP network responses indicating request status.

200OK - Request queued successfully.
400Bad Request - Missing required parameters or invalid webhook URL.
401Unauthorized - Invalid or missing Bearer token.
429Too Many Requests - Rate limit exceeded. (120 req/min).
Built for stealth. Secured by Stripe.