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.

Instagram Media Downloader

Resolves a public post, reel or carousel to its original files and returns a signed download link for every item. This endpoint answers the request itself rather than calling a webhook, because a lookup takes seconds: there is no job_id and nothing to poll. The links point at our own infrastructure, so the media never passes through a third party, and each one serves the file with a Content-Disposition attachment header.

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

Request Body

target_urlstring · required
The absolute URL of a public Instagram post, reel or carousel. Any slide's link works for a carousel. Private accounts and stories are not reachable.
test_modeboolean · optional
Runs the lookup without spending a credit, for wiring up an integration.

Response

items[]array
One entry per media item, in the order the slides were posted. Each carries type, width, height, ext, a signed url and a thumbnail. Videos come back as a single progressive MP4 with audio, never a silent video-only stream.
download_allstring | null
A single link that streams the whole gallery as a zip. Null for a post with one item.
expires_atunix seconds
When the signed links stop working, six hours after the call. Fetch the files before then, or call the endpoint again for fresh links.

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. Payments secured by Lemon Squeezy.