# Facebook URL to ID Resolver (`automation-lab/facebook-url-to-id-resolver`) Actor

Resolve public Facebook URLs into stable numeric IDs, normalized links, and typed page, profile, group, event, post, video, or photo records.

- **URL**: https://apify.com/automation-lab/facebook-url-to-id-resolver.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Facebook URL to ID Resolver

Turn batches of public Facebook URLs into stable numeric IDs, normalized URLs, and typed records.
The Actor handles common page, profile, group, event, post, video, and photo URL formats.
It is designed for data teams that need a reliable **facebook URL to ID** step before enrichment, matching, API calls, or spreadsheet export.

### What does this Actor do?

Facebook links come in many shapes.
A profile may use `profile.php?id=...`, a video may put its ID in the path, and a named page may contain no number at all.
This Actor standardizes those shapes into one output contract.

For each input URL it returns:

- the original URL;
- a normalized HTTPS Facebook URL without common tracking parameters;
- the numeric Facebook object ID when it can be determined safely;
- the detected object type;
- the resolution method;
- an explicit `resolved` or `unresolved` status;
- a per-URL error instead of a guessed ID.

Numeric formats are resolved locally without fetching Facebook.
Single-segment named public pages use Facebook's public Page Plugin.

### Who is it for?

#### Data engineers

Normalize social identifiers before loading records into a warehouse or calling a downstream API.

#### CRM and enrichment teams

Convert page and profile links collected from websites into joinable ID fields.

#### Researchers and analysts

Clean mixed Facebook URLs before comparing datasets or exporting them to a spreadsheet.

#### Automation builders

Place a deterministic resolver step between URL collection and Facebook content extraction.

### Why use this resolver?

- **Batch input:** process up to 10,000 URLs in one run.
- **Typed output:** distinguish pages, profiles, groups, events, posts, videos, and photos.
- **Safe behavior:** unresolved aliases are reported, never fabricated.
- **Low-cost path:** numeric URLs do not require a browser, proxy, or Facebook request.
- **Alias normalization:** named public page aliases can resolve to the same stable ID.
- **Integration-ready:** every input gets a predictable dataset row.

### Supported Facebook URL formats

| URL shape | Type | Resolution |
| --- | --- | --- |
| `/profile.php?id=4` | profile | `id` query parameter |
| `/people/name/123...` | profile | numeric path segment |
| `/123...` | profile or page | numeric path segment |
| `/groups/123...` | group | numeric path segment |
| `/groups/name/posts/123...` | post | numeric post segment |
| `/events/123...` | event | numeric path segment |
| `/PageName/posts/123...` | post | numeric path segment |
| `/PageName/videos/123...` | video | numeric path segment |
| `/watch/?v=123...` | video | `v` query parameter |
| `/photo.php?fbid=123...` | photo | `fbid` query parameter |
| `/permalink.php?story_fbid=123...` | post | `story_fbid` query parameter |
| `/PageAlias` | page | public Facebook Page Plugin lookup |

The Actor accepts `facebook.com`, mobile Facebook hosts, and `fb.com`.
It normalizes them to `https://www.facebook.com/`.

### Getting started

1. Open the Actor input.
2. Add one or more public Facebook URLs to **Facebook URLs**.
3. Optionally lower **Maximum URLs to process** for a sample.
4. Click **Start**.
5. Open the default dataset when the run finishes.
6. Filter on `status = resolved` before sending IDs to downstream systems.

The default prefill uses real Nintendo page, group-post, and video URLs.
It is suitable for a small first run.

### Input parameters

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `startUrls` | array | yes | real Facebook examples | Facebook URLs as request-list objects or strings |
| `maxItems` | integer | no | `100` | maximum URLs processed, from 1 to 10,000 |

Example input:

```json
{
  "startUrls": [
    { "url": "https://www.facebook.com/nintendo" },
    { "url": "https://www.facebook.com/profile.php?id=4" },
    { "url": "https://www.facebook.com/NintendoAmerica/videos/432168259120897/" }
  ],
  "maxItems": 3
}
```

### Output fields

| Field | Nullable | Meaning |
| --- | --- | --- |
| `sourceUrl` | no | exact input URL |
| `normalizedUrl` | no | canonicalized Facebook URL |
| `facebookId` | yes | stable numeric ID when resolved |
| `objectType` | no | detected object category |
| `parentId` | yes | numeric owner or parent explicitly present in the URL |
| `resolutionMethod` | no | `url_path`, `query_parameter`, `facebook_page_plugin`, or `unresolved` |
| `status` | no | `resolved` or `unresolved` |
| `error` | yes | explanation when unresolved |
| `resolvedAt` | no | ISO 8601 processing timestamp |

### Output example

A current named-page lookup produces a record shaped like this:

```json
{
  "sourceUrl": "https://www.facebook.com/nintendo",
  "normalizedUrl": "https://www.facebook.com/nintendo",
  "facebookId": "119240841493711",
  "objectType": "page",
  "parentId": null,
  "resolutionMethod": "facebook_page_plugin",
  "status": "resolved",
  "error": null,
  "resolvedAt": "2026-08-02T04:00:00.000Z"
}
```

Unresolved URLs still produce a row.
Their `facebookId` is `null`, `status` is `unresolved`, and `error` explains why.
Unresolved rows are not charged as item events.

### How much does it cost to resolve Facebook URLs to IDs?

The Actor uses pay-per-event pricing.
There is a one-time **Start** event of **$0.005 per run**.
Each successfully resolved row emits one **Item processed** event.
Unresolved rows have no item charge.

Current item prices decrease by plan tier:

| Tier | Price per resolved item |
| --- | ---: |
| Free | $0.0016479 |
| Bronze | $0.0014329 |
| Silver | $0.0011177 |
| Gold | $0.00085975 |
| Platinum | $0.00057317 |
| Diamond | $0.00040122 |

At the Bronze price, excluding Apify platform usage:

- 1 resolved URL costs about **$0.00643** including the start event;
- 100 resolved URLs cost about **$0.14829**;
- 1,000 resolved URLs cost about **$1.43790**.

Actual charges follow the tier active for your Apify account.

### Resolution strategy

The Actor first inspects the URL structure.
This covers numeric IDs at zero Facebook network cost.

If the URL is a single named page alias, the Actor calls Facebook's public Page Plugin and extracts its explicit `pageID` field.
Transient HTTP failures are retried with bounded backoff.
The resolver does not use a browser or proxy by default.

It does not infer an ID from a display name, image URL, or unrelated search result.
That prevents false joins in downstream systems.

### Batch and data-pipeline patterns

#### Prepare URLs for enrichment

Collect Facebook links from company websites, run this Actor, then pass only resolved IDs into an enrichment API.

#### Normalize aliases before deduplication

Resolve multiple named page aliases and group records by `facebookId` instead of URL text.

#### Export to a spreadsheet

Use the Apify dataset CSV or XLSX endpoint and retain `status` and `error` columns for review.

#### Schedule recurring cleanup

Schedule the same Task to normalize newly collected URLs.
This Actor reports current resolution results; it does not compare runs or send alerts itself.

### API usage with cURL

Replace `YOUR_APIFY_TOKEN` with an Apify API token:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~facebook-url-to-id-resolver/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startUrls": [
      {"url": "https://www.facebook.com/nintendo"}
    ],
    "maxItems": 1
  }'
```

### API usage with JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/facebook-url-to-id-resolver').call({
  startUrls: [
    { url: 'https://www.facebook.com/nintendo' },
    { url: 'https://www.facebook.com/profile.php?id=4' }
  ],
  maxItems: 2
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### API usage with Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("automation-lab/facebook-url-to-id-resolver").call(run_input={
    "startUrls": [
        {"url": "https://www.facebook.com/nintendo"},
        {"url": "https://www.facebook.com/profile.php?id=4"},
    ],
    "maxItems": 2,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/facebook-url-to-id-resolver"
```

#### Claude Desktop setup

Add this JSON to Claude Desktop's MCP configuration.

#### Cursor and VS Code setup

Use the same remote-server JSON in Cursor or VS Code's MCP server settings:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/facebook-url-to-id-resolver"
    }
  }
}
```

Example prompts:

- "Resolve these Facebook page URLs and return their stable IDs."
- "Normalize this batch of Facebook group, post, and video links for a CSV export."
- "Show only resolved Facebook IDs and their object types."

### Limits and expected failure behavior

- Named public **pages** are supported through the Page Plugin.
- Named personal profiles and named groups may not expose a public numeric ID.
- Opaque `pfbid...` identifiers are not guessed or decoded.
- Login-only, private, deleted, age-gated, or region-restricted objects may remain unresolved.
- `facebookId` is a string so large IDs retain precision.
- A direct numeric URL can be parsed even if the object later becomes unavailable.
- Facebook can change public embed behavior without notice.
- The Actor resolves IDs; it does not scrape posts, comments, followers, or private metadata.

When one URL fails, the run continues and records that URL as unresolved.
Invalid non-Facebook input also becomes an unresolved diagnostic row.
A missing `startUrls` input fails the run with a clear error.

### Tips for reliable runs

- Prefer canonical public desktop URLs.
- Keep numeric IDs in URLs when your upstream source provides them.
- Filter by `status` before calling another API.
- Store `sourceUrl` as lineage and use `facebookId` for joins.
- Use `maxItems` to test a subset of a large batch.
- Review unresolved rows instead of silently discarding them.

### Troubleshooting

#### Why is a named group unresolved?

The public Page Plugin resolves pages, not every named group.
Use a group URL containing its numeric group ID when available.
A group post URL with a numeric post segment can still resolve the post ID.

#### Why does a `pfbid` post return no numeric ID?

`pfbid` is an opaque Facebook identifier.
The Actor will not produce an unsafe numeric guess.
Use a URL format containing a stable numeric post ID.

#### Why do two page aliases return the same ID?

That is expected when Facebook redirects both aliases to the same page.
The stable ID is useful for deduplication.

#### Why is the normalized URL different?

The Actor upgrades HTTP to HTTPS, uses `www.facebook.com`, removes fragments and common tracking parameters, and normalizes path slashes.

### Responsible use and legality

Use this Actor only with public URLs and data you are authorized to process.
Facebook IDs can be personal data when connected to individuals.
Follow applicable privacy, data-protection, contractual, and platform rules.
Do not use the Actor to bypass access controls or to identify private users.

The Actor does not log in, access private content, or require Facebook credentials.
You are responsible for the lawful purpose, retention, and downstream use of results.

### Related Automation Lab Actors

- [Facebook Pages Scraper](https://apify.com/automation-lab/facebook-pages-scraper) for public page details after URL resolution.
- [Facebook Posts Scraper](https://apify.com/automation-lab/facebook-posts-scraper) for post extraction workflows.
- [Facebook Events Scraper](https://apify.com/automation-lab/facebook-events-scraper) for public event data.
- [Facebook Pages Posts Scraper](https://apify.com/automation-lab/facebook-pages-posts-scraper) for page-to-post pipelines.

Use this resolver when stable identifiers and normalized links are the immediate job.
Choose a related scraper when you need full content records.

### FAQ

#### Does the Actor need a Facebook account?

No.
It uses URL parsing and a public page embed surface.

#### Does it use a proxy?

No proxy is enabled by default.
Numeric URLs need no HTTP request, while named pages use a lightweight public request.

#### Are all output rows charged?

No.
The run emits one start event, and only rows with `status: resolved` emit an item event.

#### Can it resolve 10,000 URLs?

The input supports up to 10,000 URLs.
Runtime depends on how many named page aliases require network lookup.
Numeric URL batches are substantially faster.

#### Does it return Facebook content or metadata?

No.
It returns IDs, normalized URLs, types, methods, statuses, and diagnostics.
Use a related content Actor after resolution.

#### Can I send strings instead of request-list objects through the API?

Yes.
The runtime accepts either strings or `{ "url": "..." }` entries, while the Console editor presents request-list objects.

# Actor input Schema

## `startUrls` (type: `array`):

Public facebook.com or fb.com URLs to resolve. Accepts request-list objects or strings. Numeric URL formats resolve without fetching Facebook; single-segment named page URLs use a public page lookup.

## `maxItems` (type: `integer`):

Process at most this many URLs from startUrls. Use a smaller value for a quick sample.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.facebook.com/nintendo"
    },
    {
      "url": "https://www.facebook.com/groups/germtheory.vs.terraintheory/permalink/5671657859577842/"
    },
    {
      "url": "https://www.facebook.com/NintendoAmerica/videos/432168259120897/"
    }
  ],
  "maxItems": 3
}
```

# Actor output Schema

## `overview` (type: `string`):

Default dataset with resolved and clearly marked unresolved URL records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://www.facebook.com/nintendo"
        },
        {
            "url": "https://www.facebook.com/groups/germtheory.vs.terraintheory/permalink/5671657859577842/"
        },
        {
            "url": "https://www.facebook.com/NintendoAmerica/videos/432168259120897/"
        }
    ],
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/facebook-url-to-id-resolver").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [
        { "url": "https://www.facebook.com/nintendo" },
        { "url": "https://www.facebook.com/groups/germtheory.vs.terraintheory/permalink/5671657859577842/" },
        { "url": "https://www.facebook.com/NintendoAmerica/videos/432168259120897/" },
    ],
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/facebook-url-to-id-resolver").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.facebook.com/nintendo"
    },
    {
      "url": "https://www.facebook.com/groups/germtheory.vs.terraintheory/permalink/5671657859577842/"
    },
    {
      "url": "https://www.facebook.com/NintendoAmerica/videos/432168259120897/"
    }
  ],
  "maxItems": 3
}' |
apify call automation-lab/facebook-url-to-id-resolver --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/facebook-url-to-id-resolver",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/sBIRQczKWr2bvvKZZ/builds/RO9pX677jxKRf4FX2/openapi.json