vlayer docsInstagram likers
Start an asynchronous fetch of who liked a challenge post, poll its status, and page through the result.
Liker fetching is part of engagement verification and available for Instagram challenges only, so it needs a campaign for the post. The fetch runs in the background: start it, poll the status, then read the rows from the latest successful run.
1. Start a fetch
curl -X POST "{API_BASE_URL}/admin/challenges/1/likers/refresh?maxCount=2000" \
-H "Authorization: Bearer <API_TOKEN>"| Query | Default | Range |
|---|---|---|
maxCount | 1000 | 1 to 5000 |
The route returns 202 immediately with the run's initial status:
{
"data": {
"challengeId": 1,
"status": "pending",
"fetchedCount": 0,
"totalLikes": null,
"errorMessage": null,
"startedAt": null,
"finishedAt": null,
"requestedAt": "2026-06-02T15:00:11.000Z",
"warning": "Fetched liker profiles may be lower than Instagram's visible like count because this uses a public/no-cookie scraper."
}
}This route is rate-limited to 10 requests per minute per client IP, counted across every challenge rather than per challenge. Beyond that it returns 429 RATE_LIMITED with a Retry-After header.
| Status | Meaning |
|---|---|
202 | Fetch accepted |
404 | Challenge not found |
422 | The challenge is not an Instagram challenge |
429 | Rate limit hit. Wait for Retry-After |
503 | Liker fetching is not configured on this deployment |
2. Poll the status
/admin/challenges/{challengeId}/likers/statuscurl {API_BASE_URL}/admin/challenges/1/likers/status \
-H "Authorization: Bearer <API_TOKEN>"data is the latest run, or null if no fetch has been requested for this challenge.
status | Meaning |
|---|---|
pending | Queued, not started |
running | In progress |
succeeded | Done. Rows are available |
failed | The provider reported an error. See errorMessage |
aborted | Stopped before completion |
timed_out | Exceeded the run time limit |
Poll every few seconds until status is one of the last four.
3. Read the likers
/admin/challenges/{challengeId}/likers?page=1&limit=100Returns rows from the most recent succeeded run. Empty until a run has succeeded. limit caps at 100.
{
"data": [
{
"id": 1,
"username": "jane_doe",
"fullName": "Jane Doe",
"igUserId": "1784500123",
"isPrivate": false,
"isVerified": false,
"profilePicUrl": "https://…",
"likedPost": true,
"postUrl": "https://www.instagram.com/p/ABC123/",
"totalLikes": 432
}
],
"pagination": { "page": 1, "limit": 100, "total": 428 },
"warning": "Fetched liker profiles may be lower than Instagram's visible like count because this uses a public/no-cookie scraper."
}Fetched count can be lower than the visible like count
The fetch reads what Instagram shows publicly, so fetchedCount (rows stored) is often below totalLikes (the count Instagram displays). Both values are on the status object, and the list response repeats the warning. Treat a missing handle as "not found in this fetch", not as proof the user did not like the post.
Like verification uses this same liker set. See Engagement verification.
Last updated on