Vertical Viral

API-Referenz

Die Vertical Viral API ist asynchron: Sie reichen ein Ziel ein, und wir senden die strukturierten JSON-Daten über einen Webhook an Ihre Server, sobald die Extraktion vollständig sicher abgeschlossen ist.

Authentifizierung

Alle API-Anfragen müssen mit einem Bearer-Token authentifiziert werden. Erstellen Sie Ihren geheimen API-Schlüssel hier: Entwickler-Dashboard.

Teilen Sie niemals Ihre geheimen Schlüssel. Committen Sie sie nicht auf GitHub oder Frontend-Code.

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

Startet eine asynchrone Stealth-Sitzung in unserem Proxy-Netzwerk.

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

Anfrage-Body

target_usernamestring · required
Genauer Instagram-Handle ohne das @-Symbol. Beispiel: nike
webhook_urlstring · required
HTTPS-Endpunkt auf Ihrem Server, an den wir das fertige JSON per POST senden.
depthinteger · optional
Anzahl der zu scannenden Reels. Standard 30. Max 150.
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-Antwort (200 OK)

Die sofortige Antwort bestätigt die Einreihung. Speichern Sie die job_id ab.

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

Anfrage-Body

target_usernamestring · required
The exact Instagram handle to analyze without the @ symbol.
webhook_urlstring · required
HTTPS-Endpunkt auf Ihrem Server, an den wir das fertige JSON per POST senden.

Instagram Comment Scraper

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

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

Anfrage-Body

target_urlstring · required
The absolute URL of the Instagram Reel or Post to extract comments from.
webhook_urlstring · required
HTTPS-Endpunkt auf Ihrem Server, an den wir das fertige JSON per POST senden.

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

Anfrage-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 Lieferung

Sobald der Extraktionsprozess endet (normalerweise 20-30 Sek.), feuern wir den JSON an Ihre webhook_url.

Zentrale Schlüssel im Payload

status"completed" | "failed"
Bei Fehlschlag wird eine error_message geliefert.
magnetism_scorefloat (0.0 - 10.0)
Ein eigener Performance-Index (0-10) basierend auf Basis-Raten.
outlier_statusboolean
Wird als true bewertet, wenn ein Reel 2x über dem Profil-Durchschnitt liegt.
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
      }
    ]
  }
}

Fehler & Grenzen

Standard HTTP Netzwerchantworten.

200OK - Erfolgreich in Warteschlange aufgenommen.
400Bad Request - Parameter fehlen oder ungültige URL.
401Unauthorized - Ungültiges Token.
429Too Many Requests - Limit überschritten.
Für Unauffälligkeit gebaut. Zahlungen gesichert durch Lemon Squeezy.