> **For AI agents:** this page is a focused, LLM-optimized view of a
> single Fiber AI operation. Before calling it, fetch the routing
> instructions at [`https://api.fiber.ai/llms.txt`](https://api.fiber.ai/llms.txt) and the full operation
> index at [`https://api.fiber.ai/ai-docs/index.md`](https://api.fiber.ai/ai-docs/index.md).

# socialMediaLookupBatchPolling

`POST /v1/social-media-lookup/batch/poll`

**Tags:** `Social media lookup`

Poll batch social media lookup

**Endpoint:** `https://api.fiber.ai/v1/social-media-lookup/batch/poll`

## Description

Poll for the results of a batch social media lookup. Returns partial results as they become available, with overall progress statistics.

⚡ Rate limit: 240 requests per 1 minute

## Request body (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Your Fiber API key"
    },
    "runId": {
      "type": "string",
      "description": "The ID of the batch run returned by the batch trigger endpoint."
    },
    "nextPageToken": {
      "type": [
        "string",
        "null"
      ],
      "description": "Token from the previous response to fetch the next page. Omit for the first page."
    },
    "pageSize": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "default": 50,
      "description": "Number of results to return per page (default 50, max 100)."
    }
  },
  "required": [
    "apiKey",
    "runId"
  ]
}
```

## Response — success (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "output": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "in_progress",
            "completed",
            "failed"
          ],
          "description": "Current status of the batch run."
        },
        "overallStats": {
          "type": "object",
          "properties": {
            "totalPeople": {
              "type": "integer",
              "minimum": 0,
              "description": "Total number of people in this batch."
            },
            "numCompleted": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of people whose lookup has completed (success or no-match)."
            },
            "numFailed": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of people whose lookup failed (insufficient info, error)."
            },
            "numRemaining": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of people still being processed."
            }
          },
          "required": [
            "totalPeople",
            "numCompleted",
            "numFailed",
            "numRemaining"
          ],
          "description": "Summary statistics for the entire batch."
        },
        "results": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "fullName": {
                "type": "string",
                "description": "The full name of the person this result corresponds to."
              },
              "customerProvidedId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The external ID echoed back from the input for joining results to your original dataset."
              },
              "outcome": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "FOUND_CANDIDATES",
                  "NO_CANDIDATES_FOUND",
                  "INSUFFICIENT_INFORMATION",
                  null
                ],
                "description": "Overall outcome: FOUND_CANDIDATES if at least one profile was found, NO_CANDIDATES_FOUND if the search returned nothing, INSUFFICIENT_INFORMATION if there was not enough input to search."
              },
              "candidates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "platform": {
                      "type": "string",
                      "enum": [
                        "TWITTER",
                        "LINKEDIN",
                        "INSTAGRAM",
                        "FACEBOOK",
                        "TIKTOK",
                        "YOUTUBE",
                        "THREADS",
                        "PINTEREST",
                        "BLUESKY",
                        "TWITCH",
                        "ASK_FM",
                        "STEAM",
                        "MEDIUM",
                        "YELP",
                        "TRIPADVISOR",
                        "DISCORD",
                        "OTHER"
                      ],
                      "description": "The social media platform this candidate is for."
                    },
                    "handle": {
                      "type": "string",
                      "description": "The handle or username on that platform, without any @ prefix (e.g. 'karpathy')."
                    },
                    "profileUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri",
                      "description": "Full URL to the profile on that platform (e.g. 'https://x.com/karpathy')."
                    },
                    "displayName": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The display name shown on the profile."
                    },
                    "bio": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Profile bio or description."
                    },
                    "location": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Location as displayed on the profile."
                    },
                    "followerCount": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0,
                      "description": "Number of followers on that platform."
                    },
                    "isVerified": {
                      "type": [
                        "boolean",
                        "null"
                      ],
                      "description": "Whether the account is verified on that platform."
                    },
                    "confidenceOutOf10": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 10,
                      "description": "Confidence score from 0 to 10. Higher scores indicate a stronger match."
                    },
                    "rationale": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The AI reasoning for why this profile was selected as the best match."
                    }
                  },
                  "required": [
                    "platform",
                    "handle",
                    "confidenceOutOf10"
                  ]
                },
                "description": "The best-match profiles found, one per platform. Empty if no confident matches were found."
              },
              "errorMessage": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Error message if the lookup failed for this person. Null on success."
              }
            },
            "required": [
              "fullName",
              "candidates"
            ]
          },
          "description": "One entry per person on this page."
        },
        "nextPageToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "Token for the next page of results. Null when there are no more results."
        }
      },
      "required": [
        "status",
        "overallStats",
        "results"
      ]
    },
    "chargeInfo": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charged-now"
              ]
            },
            "creditsCharged": {
              "type": "number"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsCharged"
          ],
          "description": "Credits were charged immediately for this operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charging-later"
              ]
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "message"
          ],
          "description": "Credits will be charged after the operation completes"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charged-for-async-process"
              ]
            },
            "creditsCharged": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsCharged",
            "message"
          ],
          "description": "Credits that were charged for an asynchronous operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "free"
              ]
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "message"
          ],
          "description": "No credits were charged for this operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "credits-refunded"
              ]
            },
            "creditsRefunded": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsRefunded",
            "message"
          ],
          "description": "Credits were refunded for this operation"
        }
      ]
    },
    "warnings": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Full path to extraneous field (e.g., 'searchParams.ExtraField')"
          },
          "message": {
            "type": "string",
            "description": "Warning message"
          }
        },
        "required": [
          "field",
          "message"
        ]
      },
      "description": "Warnings about extraneous fields in request"
    },
    "advice": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "Tips, recommendations, and suggestions for using this API effectively."
    }
  },
  "required": [
    "output",
    "chargeInfo"
  ],
  "additionalProperties": false
}
```

---

Canonical JSON: [`https://api.fiber.ai/openapi.json`](https://api.fiber.ai/openapi.json)
Operation index: [`https://api.fiber.ai/ai-docs/index.md`](https://api.fiber.ai/ai-docs/index.md)