# Open Graph & Link Preview Extractor (`timely_quarterstaff/social-media-scraper`) Actor
Extract the link-preview metadata a page publishes for itself - what Slack, Twitter/X and LinkedIn read when you paste a URL. Returns title, description, Open Graph & Twitter-card tags, favicon, JSON-LD, images. Pure code, no proxy/AI. Reads PUBLIC meta only; does NOT scrape private social accounts.
- **URL**: https://apify.com/timely\_quarterstaff/social-media-scraper.md
- **Developed by:** [Ahmed Moussa](https://apify.com/timely_quarterstaff) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
$1.00 / 1,000 results
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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
## Open Graph & Link Preview Extractor
Turn any public URL into the **link-preview / social-share card** it publishes for itself — the exact metadata Slack, Twitter/X, LinkedIn, Discord and iMessage read when you paste a link. Deterministic, cost-safe, no AI.
> **Honest scope:** this actor reads the **public Open Graph / Twitter-card / meta tags a page voluntarily publishes** in its own HTML ``. It does **NOT** scrape private social accounts, followers, posts, engagement or feeds. Real social-account scraping is ToS-blocked and needs paid proxies/headless browsers — that is not cost-safe and is not what this does.
### What it does
Given a public URL (or a small bounded batch), it fetches the page once and deterministically extracts:
- `title`, `description`, `canonical_url`, `site_name`, `lang`, `theme_color`, `favicon`
- `og` — Open Graph block: `{title, description, image, type, url}`
- `twitter` — Twitter Card block: `{card, title, description, image, creator, site}`
- `json_ld[]` — schema.org JSON-LD objects the page publishes
- `images[]` — representative image URLs (og/twitter image first, then page `![]()
` sources), absolutized & deduped
- `method` (which layer produced the data) and a code-owned `parse_confidence`
No proxy, no headless browser, no LLM, no paid API. **$0 idle, $0 uncovered** beyond Apify compute.
### Input
| Field | Type | Description |
|-------|------|-------------|
| `url` | string | A single public URL to build a preview for (include `https://`). |
| `urls` | array | Optional bounded list of additional URLs (capped at 50/run). |
```json
{
"url": "https://github.com/apify/apify-sdk-python",
"urls": [
"https://www.theverge.com/",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
]
}
```
### Output
One record per URL in the dataset:
```json
{
"url": "https://github.com/apify/apify-sdk-python",
"status": "completed",
"title": "GitHub - apify/apify-sdk-python: The Apify SDK for Python ...",
"description": "The Apify SDK for Python is the official library for creating Apify Actors ...",
"canonical_url": "https://github.com/apify/apify-sdk-python",
"site_name": "GitHub",
"og": {
"title": "GitHub - apify/apify-sdk-python: The Apify SDK for Python ...",
"description": "The Apify SDK for Python ...",
"image": "https://opengraph.githubassets.com/.../apify/apify-sdk-python",
"type": "object",
"url": "https://github.com/apify/apify-sdk-python"
},
"twitter": {
"card": "summary_large_image",
"title": "GitHub - apify/apify-sdk-python ...",
"description": "The Apify SDK for Python ...",
"image": "https://opengraph.githubassets.com/.../apify/apify-sdk-python",
"creator": null,
"site": "@github"
},
"favicon": "https://github.com/favicon.ico",
"json_ld": [ { "@type": "WebSite", "...": "..." } ],
"theme_color": "#1e2327",
"lang": "en",
"images": [ "https://opengraph.githubassets.com/.../apify/apify-sdk-python" ],
"parse_confidence": "high",
"method": "opengraph",
"extracted_at": "2026-06-24T10:00:00+00:00",
"error": null
}
```
### Use cases
- **Link previews** — render unfurled share cards for any URL in your own app/chat/CMS.
- **SEO & social audit** — check that pages publish valid `og:title`/`og:image`/`twitter:card` before they go live.
- **Card validation** — catch missing or oversized preview images and broken canonical/site-name tags in bulk.
### How it works
1. **SSRF-guarded fetch** — the target host is resolved and rejected if it points at a private/loopback/reserved IP; a domain blocklist refuses login-walled/ToS-hostile hosts; redirects are re-validated per hop. A single streamed GET with hard size (2 MB) and time caps fetches the page.
2. **Deterministic parse** — pure-code extraction of `` (Open Graph + Twitter + standard), ``, `<link rel=canonical/icon>`, `<html lang>`, JSON-LD and `<img>` sources. First occurrence wins (matches how preview platforms read tags). Image URLs are absolutized against the final URL.
3. **Honest confidence** — `parse_confidence` is computed in code from how many Open Graph / Twitter signals were actually present (`high`/`medium`/`low`/`none`); `method` reports the richest layer used.
### Limitations (honest)
- Reads **only what the page publishes server-side** in its HTML. Pages that render Open Graph tags client-side via JavaScript (no SSR) will return little — there is no headless browser by design (cost-safety).
- **No private social data.** Followers, posts, engagement, DMs, private profiles, paginated feeds: out of scope and not possible without paid proxies/ToS violations.
- Login-walled / ToS-restricted hosts (e.g. linkedin.com, facebook.com, instagram.com) are intentionally **blocked** and return `status: "blocked"`.
- One page per record — the actor never follows links or paginates.
- `parse_confidence`/`method` are heuristics over which tags were found, not a guarantee of correctness of the publisher's own values.
# Actor input Schema
## `url` (type: `string`):
A single public URL to build a link preview for. The actor fetches this one page and parses the link-preview metadata it publishes: title, description, canonical URL, Open Graph (og:*) tags, Twitter Card (twitter:*) tags, favicon, theme-color, lang, JSON-LD and representative images — the same data Slack/Twitter/LinkedIn read when you paste a URL. Provide a full URL including https://. Best results on pages that publish Open Graph / Twitter-card tags (news articles, blog posts, GitHub repos, YouTube watch pages, product pages — most do).
## `urls` (type: `array`):
Optional bounded list of additional URLs, each processed exactly like 'url' and added to the same dataset. Processed in addition to 'url' and capped at 50 per run for cost-safety. This is single-page extraction, one preview record per URL — the actor never follows links, paginates, or scrapes private social accounts.
## Actor input object example
```json
{
"url": "https://github.com/apify/apify-sdk-python",
"urls": [
"https://www.theverge.com/",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
]
}
```
# 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 = {
"url": "https://github.com/apify/apify-sdk-python",
"urls": [
"https://www.theverge.com/",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("timely_quarterstaff/social-media-scraper").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 = {
"url": "https://github.com/apify/apify-sdk-python",
"urls": [
"https://www.theverge.com/",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
],
}
# Run the Actor and wait for it to finish
run = client.actor("timely_quarterstaff/social-media-scraper").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 '{
"url": "https://github.com/apify/apify-sdk-python",
"urls": [
"https://www.theverge.com/",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
]
}' |
apify call timely_quarterstaff/social-media-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=timely_quarterstaff/social-media-scraper",
"--header",
"Authorization: Bearer <YOUR_API_TOKEN>"
]
}
}
}
```
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/B4Yy8AsaW2KkxU2IF/builds/Rd3xWS9qe9GPi7i3W/openapi.json