Facebook ID/Username Profile Checker API: Bulk Profiles

Check Facebook profiles and Pages by numeric profile ID, username (vanity name) or profile URL and return the profile photo (rehosted on a permanent URL), the numeric ID, the canonical username, the display name, the short tagline, and the follower and “talking about this” counts. The product reads the public, logged-out Facebook profile page only: no login is used and no friend data is collected. Profiles that do not exist, are deactivated, or are not visible to logged-out visitors are returned as not activated. The task uses the standard asynchronous batch workflow.

Input format

Upload a text file with one Facebook identifier per line. Accepted forms:

• Numeric profile ID, e.g. 4
• Username (vanity name), e.g. zuck or @zuck; letters, digits and dots, 1–50 characters, case-insensitive
• Profile URL, e.g. facebook.com/zuck, facebook.com/profile.php?id=100003012457235 or facebook.com/people/<Name>/<ID>

Non-profile facebook.com URLs (groups, pages, login and similar paths) are rejected as invalid entries.

4
zuck
@Meta
https://www.facebook.com/profile.php?id=100003012457235
https://www.facebook.com/people/Mark-Zuckerberg/4/

Create a task

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="facebook_profile"'

The API returns a task ID. Keep this ID and use it to poll the task status.

Upload response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "1.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Check task status

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Poll until status becomes exported. Do not treat pending or processing as a completed result.

Processing response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Exported response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "1.500000",
    "currency": "USD"
  }
}

Result Fields

The result CSV has the columns below, in this order: username,activated,avatar,fb_id,fb_username,name,image,tagline,followers,talking_about.

Field	Description	Example
username	Input identifier exactly as submitted (ID, username or profile URL).	4
activated	Whether a public profile page was obtained (yes/no). no means the profile does not exist, is deactivated, or is not visible to logged-out visitors; Facebook shows the same “content isn’t available” page for all three, so they cannot be distinguished.	yes
avatar	Permanent URL of the profile photo, rehosted by us on fb.waavatar.xyz. Empty when activated is no.	https://fb.waavatar.xyz/ins/62e8bb6110133ef3115f55454ff66c4d.jpg
fb_id	Numeric Facebook profile ID parsed from the page.	4
fb_username	Canonical username (vanity name) shown by Facebook; empty for ID-only profiles.	zuck
name	Display name.	Mark Zuckerberg
image	Facebook’s own signed CDN URL of the profile photo. It expires within a few days; use avatar for a durable link.	https://scontent.xx.fbcdn.net/v/…jpg?…&oe=…
tagline	Short bio text from the page description; may be empty.	Bringing the world closer together.
followers	Follower count. For Pages this is the “likes” count. Integer; empty when not shown.	121439077
talking_about	Facebook’s “talking about this” count. Integer; empty when not shown.	918893

Example rows:

username,activated,avatar,fb_id,fb_username,name,image,tagline,followers,talking_about
4,yes,https://fb.waavatar.xyz/ins/62e8bb6110133ef3115f55454ff66c4d.jpg,4,zuck,Mark Zuckerberg,https://scontent.xx.fbcdn.net/v/....jpg?...&oe=...,Bringing the world closer together.,121439077,918893
zzqqxxjjkk993827a,no,,,,,,,,

Both personal profiles and Pages are supported. For example, Meta resolves to fb_id 100080376596424 and its followers value is the Page’s likes count.

Result file handling

Download the file from result_url only after the task is exported. Preserve the returned column names when processing the file downstream.

Response fields

Field	Description
created_at	Timestamp when the task was created.
updated_at	Timestamp of the latest task status update.
task_id	Unique task identifier.
status	pending, processing, exported, or failed.
total	Total input values processed.
success	Values processed successfully.
failure	Values that failed processing.
result_url	Download URL when the task is exported.
actual_amount	Final settled amount, when available.
estimated_amount	Estimated amount returned when the task is created.

Status codes

Status	Description
200	Request successful.
202	Task created successfully and estimated charge applied.
400	Invalid file, unsupported task type, or too few valid entries.
401	Missing or invalid API key.
402	Insufficient account balance.
403	Product not available for your account (discontinued or whitelist-only); contact support.
404	Task not found.
413	Uploaded file is too large.
500	Internal server error; retry later.
503	Product temporarily unavailable (paused for maintenance); nothing is charged, retry later.

Operational notes

• The task is asynchronous; use the task ID for status polling.
• Price: $3 per 10,000 identifiers. Billing is by submitted quantity: every submitted identifier is billed whether or not a profile is found. The minimum billable quantity per task is 500 identifiers; smaller tasks are billed as 500.
• Results reflect the public profile page at check time. No caching is applied; each submission is re-checked.
• Check product-specific input limits before uploading.
• Failed rows are reported in the exported result and reflected in the task counters.
• The fields above are based on the current live sample and may change when the upstream page structure changes.