# Link Preview API - Open Graph, Meta Tags, URL Metadata (`martin10291/link-preview-open-graph`) Actor

No API key, no login. Send up to 50 URLs and get a clean link preview row for each: title, description, image, site name, favicon, type, language, canonical, author, published time, Twitter card, oEmbed endpoint and JSON-LD types. Image, PDF and video URLs get a header preview. Every failure is a ro

- **URL**: https://apify.com/martin10291/link-preview-open-graph.md
- **Developed by:** [Martin Petrov](https://apify.com/martin10291) (community)
- **Categories:** Developer tools, Automation, Business
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 API - Open Graph, Meta Tags, URL Metadata

**Problem:** your chat, CMS, newsletter, bookmark or AI agent needs a card for a pasted URL, and every site hides its title, image and description in different tags. Parsing them yourself means redirects, charsets, relative image paths and sites that point at private addresses.

**This API:** up to 50 URLs per call, fetched in parallel, one clean row per URL:

- **Card fields:** `title` (og:title, then twitter:title, then the page title), `description`, `image` (absolute URL, og:image, then twitter:image, then the first large image), `imageWidth` / `imageHeight` when the page declares them, `siteName`, `favicon` (absolute URL).
- **Page details:** `type`, `locale`, `lang`, `canonical`, `author`, `publishedTime`, `modifiedTime` when the page declares them (meta tags or schema.org JSON-LD), `themeColor`, `twitterCard`, `twitterSite`, `twitterCreator`.
- **Discovery:** `oembedUrl` (the oEmbed endpoint the page declares) and `jsonLdTypes` (schema.org types such as Article, Product, Organization).
- **Redirects:** `finalUrl` after up to 5 redirects, `redirected` flag, `httpStatus`, `contentType`.
- **Non-HTML URLs:** an image URL previews as the image itself, a PDF, video or audio URL gets a title from the file name and a type from the headers.

### Why it is different

- **Every failure is a row, never a silent empty result.** `status` is `ok`, `partial` (page fetched, no title found) or `error`, and `error` is a code: `http_403`, `http_404`, `timeout`, `dns_error`, `tls_error`, `connection_failed`, `blocked_by_robots`, `blocked_private_address`, `blocked_port`, `unsupported_scheme`, `too_many_redirects`, `empty_response`, `invalid_url`.
- **Safe to expose to your users.** Only http and https on ports 80, 443, 8080 and 8443. The host is resolved and every address must be public; private, loopback, link-local, carrier-grade NAT, multicast, reserved and IPv6-local addresses are refused, the check is repeated on every redirect hop, and the connection goes to the address that was checked.
- **Fast.** URLs are fetched in parallel; at most each page is read up to 128 KB past its head tag (1 MB hard cap) with 8 second timeouts.
- **Honest crawler.** Identifies itself as `RadarLinkPreview/1.0`, respects robots.txt, no proxies, no logins.
- **Monitor mode:** `onlyNew: true` + `monitorId` returns only URLs whose preview is new or changed.

### Example (API)

```bash
curl -X POST "https://api.apify.com/v2/acts/martin10291~link-preview-open-graph/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com", "https://en.wikipedia.org/wiki/Bulgaria"]}'
```

Output row (trimmed):

```json
{"url": "https://en.wikipedia.org/wiki/Bulgaria", "finalUrl": "https://en.wikipedia.org/wiki/Bulgaria",
 "status": "ok", "httpStatus": 200, "title": "Bulgaria - Wikipedia",
 "description": "Bulgaria is a country in Southeast Europe.",
 "image": "https://upload.wikimedia.org/wikipedia/commons/example.png", "siteName": "Wikipedia",
 "favicon": "https://en.wikipedia.org/static/favicon/wikipedia.ico", "type": "website", "lang": "en",
 "canonical": "https://en.wikipedia.org/wiki/Bulgaria", "jsonLdTypes": ["Article"],
 "contentType": "text/html", "redirected": false, "error": null, "checkedAt": "2026-11-12T10:00:00Z"}
```

A blocked URL looks like this:

```json
{"url": "http://169.254.169.254/latest/meta-data/", "status": "error", "error": "blocked_private_address", "title": null}
```

### Schedule and monitor

Run it on a schedule (hourly or daily) with `onlyNew: true` and a `monitorId` such as `my-links`. The first run returns every URL; later runs return one row per URL whose title, description, image, canonical or type changed, with `change` set to `first_check` or `changed`. Errors are always returned (`change: error`). Chain it with a webhook to refresh the cards in your app only when a page changed.

### Use from agents (MCP)

Add the Apify MCP server (`https://mcp.apify.com?tools=martin10291/link-preview-open-graph`) to Claude, Cursor or any MCP client and ask: "Give me the title, description and image of these links: ...".

### Input

| Field | What it does |
|---|---|
| `urls` | URLs to preview, up to 50 (a single `url` also works) |
| `onlyNew` / `monitorId` | Return only URLs whose preview is new or changed for this Monitor ID |

### Honest limits

- **No JavaScript rendering.** A single-page app that writes its tags with JavaScript returns what the server sends; those pages can come back `partial`.
- **Pages that block automated requests** (login walls, bot checks, HTTP 403) return an error row. We do not use proxies or evade bot checks.
- **robots.txt is respected.** A URL disallowed for our user agent returns `blocked_by_robots`.
- The page is read up to 128 KB past the end of its head section (hard cap 1 MB); tags placed after that are not seen.
- Favicon falls back to `/favicon.ico` of the site when the page declares none; that file is not fetched to confirm it exists.
- `author` and `publishedTime` are returned only when the page declares them.

### FAQ

**Pricing?** $1.00 per 1,000 result rows (one row per URL, or per new or changed URL in monitor mode).
**Do I need a key?** No.
**What happens with localhost or an internal IP?** The row comes back with `blocked_private_address`; nothing is fetched.
**Is the data cached?** No. Every call fetches the page live.

# Actor input Schema

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

Web page, image, PDF or video URLs to preview, up to 50 per run (http or https; a URL without a scheme gets https). Each URL returns one row. Private, internal and localhost addresses are refused with an error row.

## `onlyNew` (type: `boolean`):

Return a row only for URLs whose preview (title, description, image, canonical, type) is new or changed since the last run with this Monitor ID. The first run returns every URL. Errors are always returned. Use it on a schedule to watch pages.

## `monitorId` (type: `string`):

Name of the watch list for Only changed previews mode, e.g. my-links. Each Monitor ID keeps its own memory.

## Actor input object example

```json
{
  "urls": [
    "https://example.com",
    "https://en.wikipedia.org/wiki/Bulgaria"
  ],
  "onlyNew": false,
  "monitorId": "default"
}
```

# Actor output Schema

## `results` (type: `string`):

One row per URL: final URL, status, title, description, image, site name, favicon, type, language, canonical, author, published time, Twitter card fields, theme colour, oEmbed endpoint, JSON-LD types and content type, or an error code. In Only changed previews mode one row per new or changed URL.

# 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://example.com",
        "https://en.wikipedia.org/wiki/Bulgaria"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("martin10291/link-preview-open-graph").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://example.com",
        "https://en.wikipedia.org/wiki/Bulgaria",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("martin10291/link-preview-open-graph").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://example.com",
    "https://en.wikipedia.org/wiki/Bulgaria"
  ]
}' |
apify call martin10291/link-preview-open-graph --silent --output-dataset

```

## MCP server setup

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

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/DZwZ2fnXCgbMZtJZX/builds/bUYJF1nresoRuwwt0/openapi.json