vlayervlayer docs
API reference

Data lookups

Read a public Instagram or TikTok post's metrics and comments from its URL, or a creator's profile from their handle. Nothing is stored.

Fetch post details and engagement stats

Fetch normalized post content, its owner, and engagement counts. Use owner.accountId, not the handle in the URL, to verify ownership. A metric is null when the platform does not expose it.

GET
/v1/stats

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Query Parameters

urlRequiredstring

Instagram post/reel or TikTok video URL.

Format: "uri"
curl -X GET "//v1/stats?url=http%3A%2F%2Fexample.com" \
  -H "Authorization: Bearer <token>"

Current post details and metrics

{
  "platform": "instagram",
  "contentType": "post",
  "postUrl": "http://example.com",
  "owner": {
    "handle": "string",
    "accountId": "string",
    "secUid": "string",
    "displayName": "string"
  },
  "post": {
    "caption": "string",
    "postedAt": "2019-08-24T14:15:22Z",
    "thumbnailUrl": "http://example.com",
    "mediaUrls": [
      "http://example.com"
    ]
  },
  "stats": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "saves": 0
  },
  "source": "provider"
}

Fetch stats for up to 25 posts in one call

Fetches the same data as GET /v1/stats for up to 25 post URLs (Instagram and TikTok can be mixed). Results come back in input order.

Per-URL outcome: each result is either ok: true with the GET /v1/stats fields, or ok: false with the error code that URL would have returned on its own (e.g. POST_NOT_FOUND, SCRAPING_RATE_LIMITED). Individual lookup failures do not change the 200 response for an accepted batch; a malformed body or rate-limit rejection returns 422 or 429 before processing. Check each result's ok and the summary counts.

Limits and usage: each input URL consumes one of the 60 per-IP batch URL units per minute. Duplicate URLs are fetched once, returned in each original position, and billed once. Each unique URL that succeeds before the 100-second batch deadline counts as one billable unit in GET /auth/usage; failed or timed-out URLs are not billed.

Lookups run concurrently. URLs still incomplete at the deadline return BATCH_TIMEOUT.

POST
/v1/stats/batch

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Request Body

application/jsonRequired
urlsRequiredarray<string>

Instagram post/reel or TikTok video URLs. Invalid URLs are returned as per-item VALIDATION_ERROR results.

curl -X POST "//v1/stats/batch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "string"
    ]
  }'

One result per input URL, in input order

{
  "results": [
    {
      "url": "string",
      "ok": true,
      "platform": "instagram",
      "contentType": "post",
      "postUrl": "http://example.com",
      "owner": {
        "handle": "string",
        "accountId": "string",
        "secUid": "string",
        "displayName": "string"
      },
      "post": {
        "caption": "string",
        "postedAt": "2019-08-24T14:15:22Z",
        "thumbnailUrl": "http://example.com",
        "mediaUrls": [
          "http://example.com"
        ]
      },
      "stats": {
        "views": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "saves": 0
      },
      "source": "provider"
    }
  ],
  "summary": {
    "total": 0,
    "succeeded": 0,
    "failed": 0
  }
}

Fetch one page of comments

Fetch comments for an Instagram post/reel or TikTok video. Pass nextCursor back as cursor until hasMore is false. A successful empty list means the post has no comments.

GET
/v1/comments

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Query Parameters

urlRequiredstring

Instagram post/reel or TikTok video URL.

Format: "uri"
cursorstring

nextCursor from the previous response.

curl -X GET "//v1/comments?url=http%3A%2F%2Fexample.com&cursor=string" \
  -H "Authorization: Bearer <token>"

One page of comments

{
  "platform": "instagram",
  "postUrl": "http://example.com",
  "comments": [
    {
      "id": "string",
      "username": "string",
      "text": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "likeCount": 0,
      "replyCount": 0
    }
  ],
  "nextCursor": "string",
  "hasMore": true
}

Fetch a creator profile

Fetch a normalized Instagram or TikTok profile. Handles may be supplied with or without @. profile.accountId is stable across handle changes.

GET
/v1/profile

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Query Parameters

platformRequiredstring
Value in: "instagram" | "tiktok"
handleRequiredstring

Handle only, not a profile URL.

curl -X GET "//v1/profile?platform=instagram&handle=string" \
  -H "Authorization: Bearer <token>"

Current public profile

{
  "platform": "instagram",
  "profile": {
    "handle": "string",
    "accountId": "string",
    "secUid": "string",
    "displayName": "string",
    "bio": "string",
    "profilePictureUrl": "http://example.com",
    "isVerified": true,
    "isPrivate": true,
    "followerCount": 0,
    "mediaCount": 0
  }
}

Last updated on

Webhooks

Register a webhook for your brand, verify the HMAC-SHA256 signature, and handle the three events.

Posts

Read a public Instagram or TikTok post's cover image straight from its URL, before a campaign exists for it.