vlayerInstagram likers
Start an asynchronous fetch of who liked a challenge post, poll its status, and page through the result.
Liker fetching is available for Instagram challenges only. The fetch runs in the background: start it, poll the status, then read the rows from the latest successful run.
1. Start a fetch
POST /admin/challenges/{challengeId}/likers/refresh?maxCount=1000
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 scraper."
}
}This route is rate-limited to 10 requests per minute. 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
GET /admin/challenges/{challengeId}/likers/status
curl {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
GET /admin/challenges/{challengeId}/likers?page=1&limit=100
Returns 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 scraper."
}Fetched count can be lower than the visible like count
The fetch uses a public scraper, 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 Verify engagement.