# Link Preview Metadata (OG + JSON-LD): Bulk URL Extractor (`transparent_meteorite/link-preview-metadata-extractor`) Actor

Bulk link preview data for any list of URLs: Open Graph, Twitter Card, favicon and touch icon, og:image size, canonical, oEmbed, JSON-LD types and a 0-100 preview quality score with fix hints. Plain HTTP, failed URLs never charged.

- **URL**: https://apify.com/transparent_meteorite/link-preview-metadata-extractor.md
- **Developed by:** [Detroit Web Agent - Open Data](https://apify.com/transparent_meteorite) (community)
- **Categories:** SEO tools, Developer tools, Social media
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.95 / 1,000 preview extracteds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Link Preview Metadata Extractor

Give it a list of URLs and get back, for each one, what a link preview card would show: title, description, image with its size, site name and favicon. You also get every Open Graph and Twitter Card tag, the canonical URL, oEmbed links, JSON-LD types and a 0-100 preview quality score with fix hints. It uses plain HTTP: no browser, no login, no proxy needed for most sites.

### What data you get

- **Preview card:** title, description, image (absolute URL), image width, height and alt, site name, favicon, apple-touch-icon
- **Tags:** all `og:*` and `twitter:*` tags, canonical, `<title>`, meta description, lang, theme color, author, published and modified time
- **Discovery:** oEmbed JSON/XML links, RSS/Atom feeds, web app manifest, JSON-LD `@type`s
- **Fetch facts:** final URL after redirects, redirect chain, HTTP status, content type, response time
- **Quality:** `previewQuality` (0-100), letter grade, missing tags and plain-English fixes

### Use cases

- Unfurl links pasted into a chat, CRM, newsletter or bookmark app, with the image size known up front
- Check landing pages before a campaign so none of them share as a blank card
- Enrich a list of article or company URLs with canonical URL, language, dates and feeds

### How it works

1. Each URL is fetched over HTTPS with a normal desktop browser user agent. Redirects are followed (up to 10) and recorded.
2. Only HTML answers are parsed. PDFs, images and other files are detected from the headers and skipped without downloading them.
3. Pages are read up to 2 MB; larger pages are parsed from the first 2 MB (`htmlTruncated` tells you).
4. Tags are read in the same fallback order link unfurlers use: Open Graph first, then Twitter Card, then plain HTML and JSON-LD.
5. Relative image, icon and canonical URLs are turned into absolute URLs.
6. Every URL gets a row, including failures, so you can match the output back to your list with `inputIndex`. Only successful previews are charged.

### Input

| Field | What it does | Default |
|---|---|---|
| `urls` | Public page URLs, one per line (up to 5,000). URLs without `https://` get it added; duplicates are removed. | required |
| `maxUrls` | Upper limit of URLs processed in one run. | 1000 |
| `requestTimeoutSecs` | Time limit per URL, redirects included (3-60 seconds). | 15 |
| `maxConcurrency` | Pages fetched at the same time (1-25). | 10 |
| `includeRawTags` | Keep the full `openGraph`, `twitterCard` and `icons` objects. Turn off for a flat CSV. | true |
| `proxyConfiguration` | Optional Apify Proxy or your own proxies, for sites that refuse cloud IPs. | off |

#### Example input

```json
{
  "urls": ["https://www.python.org", "https://developer.mozilla.org/en-US/docs/Web/HTML", "apify.com"],
  "requestTimeoutSecs": 15,
  "maxConcurrency": 10
}
```

### Output

One dataset row per input URL. The **Previews** view shows the card fields and score, **SEO tags** shows title, description, canonical, language and JSON-LD types, and **Fetch status** shows status codes, errors and what was charged. Download as JSON, CSV, Excel or HTML, or read it through the API. A run summary (counts, errors by code, charged events) is saved as the `OUTPUT` record in the key-value store.

#### Sample output

Trimmed row for `https://www.python.org` (the raw `openGraph`, `twitterCard`, `icons` and `ogImages` objects are left out here):

```json
{
  "inputUrl": "https://www.python.org/",
  "url": "https://www.python.org/",
  "statusCode": 200,
  "ok": true,
  "billed": true,
  "title": "Welcome to Python.org",
  "description": "The official home of the Python Programming Language",
  "image": "https://www.python.org/static/opengraph-icon-200x200.png",
  "imageWidth": null,
  "siteName": "Python.org",
  "favicon": "https://www.python.org/static/favicon.ico",
  "faviconSource": "declared",
  "appleTouchIcon": "https://www.python.org/static/apple-touch-icon-144x144-precomposed.png",
  "ogType": "website",
  "lang": "en",
  "feedUrls": ["https://blog.python.org/feeds/posts/default?alt=rss", "https://www.python.org/downloads/feed.rss"],
  "jsonLdTypes": ["WebSite", "SearchAction"],
  "previewQuality": 78,
  "previewGrade": "B",
  "missingTags": ["og:image:width/height", "og:image:alt", "twitter:card", "canonical"],
  "hints": ["Add og:image:width and og:image:height so Facebook and LinkedIn render the image on the very first share instead of after a background scrape.", "..."],
  "fetchedAt": "2026-11-08T06:01:46.070Z"
}
```

A failed URL looks like `{"inputUrl": "https://example.com/missing", "ok": false, "error": "http-404", "billed": false, ...}`. Error codes include `timeout`, `dns-not-found`, `connection-refused`, `tls-error`, `http-403`, `http-404`, `http-500` (any status as `http-<code>`), `not-html`, `empty-body`, `too-many-redirects` and `blocked-non-public-url`.

### Preview quality score

The score adds up points for the tags that decide how a shared link looks: og:title (12), og:description (8), og:image (18), declared image size (4), https image (3), image alt (3), og:url (4), og:type (4), og:site_name (4), twitter:card (10), a 10-70 character title (8), a 50-170 character meta description (6), canonical (5), a declared favicon (5), apple-touch-icon (3) and html lang (3). Grades: A 90+, B 75+, C 60+, D 40+, F below 40. Every missing item comes with a one-line fix in `hints`.

### Pricing

Pay per event, no monthly fee:

- **Preview extracted:** $0.00095 per URL that returned an HTML page and was parsed ($0.95 per 1,000).
- **Actor start:** $0.00005 per run.

URLs that time out, fail DNS, answer 4xx/5xx, are not HTML, or are private/local addresses are listed in the dataset but **never charged**. If no input URL is usable the run stops at once with a clear message. Set "Maximum cost per run" in the run options to cap spend; the actor stops cleanly at that limit.

### Call it from code

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("transparent_meteorite/link-preview-metadata-extractor").call(run_input={"urls": ["https://www.python.org", "https://github.com"]})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["url"], row["title"], row["image"])
```

cURL (starts a run and waits for the rows):

```bash
curl -X POST "https://api.apify.com/v2/acts/transparent_meteorite~link-preview-metadata-extractor/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN"   -H "Content-Type: application/json"   -d '{"urls": ["https://www.python.org"]}'
```

The actor also works as a tool for AI agents through the Apify MCP server (`https://mcp.apify.com`), using the same input.

### FAQ

**Does it run JavaScript?** No. It reads the HTML the server sends, which is also what Slack, LinkedIn, X and most unfurlers read. Pages that only add their tags with client-side JavaScript will show the tags present in the server HTML.

**Why did a site return 403?** Some sites refuse requests from cloud data centers. Turn on Apify Proxy in `proxyConfiguration` and retry those URLs. The actor does not bypass captchas or logins; pages behind them come back as errors and are not charged.

**Is the favicon always real?** `faviconSource` says `declared` when the page links an icon and `default-guess` when the actor fell back to `/favicon.ico` on the site root.

**Can I schedule it?** Yes. Save a task with your URL list and add a schedule; each run writes a new dataset you can send to a webhook, Make, Zapier or n8n.

### Limits

- Up to 5,000 URLs per run; 2 MB of HTML per page; 10 redirects per URL.
- Only public http(s) URLs: localhost, private IP ranges and non-web schemes are refused.
- Tags added only by client-side JavaScript are not seen.
- A page answering 202 or another non-200 success code (often a bot check) is reported as an error, not parsed.

### Related actors

- [Technical SEO Page Audit](https://apify.com/transparent_meteorite/technical-seo-page-audit): on-page SEO checks for the same URLs.
- [Sitemap Link Inventory](https://apify.com/transparent_meteorite/sitemap-link-inventory): get every URL of a site from its sitemaps, then preview them here.
- [Website Tech Stack Detector](https://apify.com/transparent_meteorite/website-tech-stack-detector): see which CMS, analytics and frameworks each site runs.

# Actor input Schema

## `urls` (type: `array`):

Public page URLs, one per line, e.g. https://www.example.com/blog/post. Up to 5,000 per run; duplicates are removed and URLs without a scheme get https://.

## `maxUrls` (type: `integer`):

Upper limit on how many input URLs are processed in one run (hard cap 5,000), e.g. 100 for a quick sample. Extra URLs are skipped and never charged.

## `requestTimeoutSecs` (type: `integer`):

How long to wait for one page (all redirects included) before giving up, e.g. 15. Slow pages that time out are listed with error "timeout" and are not charged.

## `maxConcurrency` (type: `integer`):

How many pages are fetched at the same time, e.g. 10. Requests to the same site are spaced out politely; lower this if a site starts answering 429.

## `includeRawTags` (type: `boolean`):

Keep the full openGraph, twitterCard and icons objects in each row. Turn off for a smaller, flat CSV export.

## `proxyConfiguration` (type: `object`):

Optional. Requests go out directly by default, which suits most public sites. Turn on Apify Proxy (for example the datacenter group) only for sites that block cloud IP addresses; proxy traffic is billed by Apify on top.

## Actor input object example

```json
{
  "urls": [
    "https://apify.com",
    "https://www.python.org",
    "https://developer.mozilla.org/en-US/docs/Web/HTML",
    "https://en.wikipedia.org/wiki/Open_Graph_protocol",
    "https://www.bbc.com/news"
  ],
  "maxUrls": 1000,
  "requestTimeoutSecs": 15,
  "maxConcurrency": 10,
  "includeRawTags": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

No description

## `seo` (type: `string`):

No description

## `fetch` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {
    "urls": [
        "https://apify.com",
        "https://www.python.org",
        "https://developer.mozilla.org/en-US/docs/Web/HTML",
        "https://en.wikipedia.org/wiki/Open_Graph_protocol",
        "https://www.bbc.com/news"
    ],
    "maxUrls": 1000,
    "requestTimeoutSecs": 15,
    "maxConcurrency": 10,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("transparent_meteorite/link-preview-metadata-extractor").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 = {
    "urls": [
        "https://apify.com",
        "https://www.python.org",
        "https://developer.mozilla.org/en-US/docs/Web/HTML",
        "https://en.wikipedia.org/wiki/Open_Graph_protocol",
        "https://www.bbc.com/news",
    ],
    "maxUrls": 1000,
    "requestTimeoutSecs": 15,
    "maxConcurrency": 10,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("transparent_meteorite/link-preview-metadata-extractor").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "urls": [
    "https://apify.com",
    "https://www.python.org",
    "https://developer.mozilla.org/en-US/docs/Web/HTML",
    "https://en.wikipedia.org/wiki/Open_Graph_protocol",
    "https://www.bbc.com/news"
  ],
  "maxUrls": 1000,
  "requestTimeoutSecs": 15,
  "maxConcurrency": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call transparent_meteorite/link-preview-metadata-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,transparent_meteorite/link-preview-metadata-extractor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

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