vlayer docsQuickstart
Go from a public post URL to its comments and metrics in five Social Data API calls.
Before you start
Book a call (opens in a new tab) to get your API token, base URL and brandId. The examples write them as <API_TOKEN>, {API_BASE_URL} and 1. You also need the URL of a public Instagram post or reel, or a TikTok video.
Check the post
Confirm the URL points at a post the API can read. The check reads the platform, so it is a data lookup, but nothing is stored.
curl -G {API_BASE_URL}/admin/posts/thumbnail \
-H "Authorization: Bearer <API_TOKEN>" \
--data-urlencode "url=https://www.instagram.com/p/ABC123/?igsh=xyz"{
"data": {
"platform": "instagram",
"contentType": "post",
"contentId": "ABC123",
"canonicalUrl": "https://www.instagram.com/p/ABC123/",
"thumbnailUrl": "https://..."
}
}Keep canonicalUrl: it is the cleaned-up URL to use in the next step. Most posts answer in about a second; a few take up to 40 seconds, so set a generous client timeout. A 404 or 422 means the post cannot be read and the later steps would fail too; see Data lookup errors.
Create a campaign for the post
Lookups on a post are addressed by a challengeId, and you get one by creating a campaign with the post as its challenge.
curl -X POST {API_BASE_URL}/admin/campaigns \
-H "Authorization: Bearer <API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"brandId": 1,
"title": "Launch post",
"pointsReward": 0,
"challenge": { "targetUrl": "https://www.instagram.com/p/ABC123/" }
}'{
"data": {
"campaign": { "id": 1, "brandId": 1, "title": "Launch post", "isActive": true },
"challenge": { "id": 1, "campaignId": 1, "platform": "instagram", "contentId": "ABC123" }
}
}Store data.challenge.id. pointsReward is required; it only matters if you use engagement verification.
Fetch the comments
This data lookup reads the post and stores its comments.
curl -X POST {API_BASE_URL}/admin/challenges/1/comments/refresh \
-H "Authorization: Bearer <API_TOKEN>"{ "data": { "totalFetched": 347, "sweepStatus": "swept", "historyComplete": true } }Read the comments
Reading stored comments does not touch the platform, so page through them as often as you like.
curl "{API_BASE_URL}/admin/challenges/1/comments?page=1&limit=50" \
-H "Authorization: Bearer <API_TOKEN>"{
"data": [
{
"id": 1,
"platformCommentId": "17890012345678",
"username": "creator_jane",
"commentText": "Love this product!",
"commentedAt": "2026-06-02T14:21:07.000Z"
}
],
"pagination": { "page": 1, "limit": 50, "total": 347 }
}Fetch the post's metrics
Another data lookup on the same challenge.
curl -X POST {API_BASE_URL}/admin/challenges/1/metrics/refresh \
-H "Authorization: Bearer <API_TOKEN>"{
"data": {
"likeCount": 5432,
"commentCount": 347,
"shareCount": 89,
"viewCount": null,
"thumbnailUrl": "https://...",
"fetchedAt": "2026-06-02T15:00:11.000Z"
}
}A 202 instead of a 200 means the refresh was queued; see Post metrics.
What you have now
A campaign and its challenge, the post's comments stored and readable, and a first metrics snapshot. Call the two refresh routes again whenever you want newer data; the GET routes always return what was stored last.
Last updated on