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.

Instagram Post Scraper

Every post of a public profile, newest first: its link, date, type, likes, comments, reel views, caption, collaborators, paid partnership flag, tagged accounts, location and audio. A run reads the profile in a real browser, so a large one takes minutes: the request returns a job_id at once, and the posts reach you by webhook, by polling, or both.

POSThttps://verticalviral.io/api/scrape/postsscraper
GEThttps://verticalviral.io/api/scrape/postsscraper?job_id=<job_id>

Request Body

target_usernamestring · required
The profile's username, with or without the @, or its profile link. Private profiles cannot be read.
max_postsinteger · optional
How many of the newest posts to collect, from 1 to 1,000. Defaults to 100. A run costs one credit per 100 posts of max_posts, taken when the run is accepted; when it ends, the credits for posts it did not find come back, and a run that fails costs nothing.
webhook_urlstring · optional
A public HTTPS endpoint we POST the result to when the run ends: job_id, status (success or error), posts_found, data (the posts), credits_charged and credits_refunded. Leave it out to poll instead.

Response

202 AcceptedPOST
job_id, max_posts, credits_charged, credits_remaining and results_url, the GET address of this run. 402 when the credits do not cover the run; 429 while three of your runs are still in progress.
200 OKGET
status (pending, processing, completed or error), posts_found so far, and data, the posts, once the run is completed. Add &partial=true to get the posts found so far while it runs.
data[]array
One object per post, newest first: post_url, type (reel, carousel, photo or video), posted_at (ISO 8601), likes, comments, views (reels), caption, carousel_count, owner, collaborators, paid_partnership, tagged, location, audio, duration_s, is_pinned, likes_hidden and thumbnail. A count Instagram does not show is null.

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.