# Social Preview Validator - Open Graph & Twitter Cards (`quanmatrix/social-preview-validator`) Actor

Validate Open Graph, Twitter/X card, canonical, and social preview image health for public URLs in bulk, returning structured metadata, issue flags, and a 0-100 QA score.

- **URL**: https://apify.com/quanmatrix/social-preview-validator.md
- **Developed by:** [Rafael Barreto Haddad](https://apify.com/quanmatrix) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.64 / 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?

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

## Social Preview Validator - Open Graph & Twitter Cards

Check how public web pages are prepared for social sharing before broken titles, missing descriptions, or dead preview images reach production. The Actor validates Open Graph, Twitter/X card metadata, canonical links, and preview-image reachability, then returns structured issues and a 0-100 score.

### Why use this Actor

Manual preview checks do not scale across product catalogs, editorial archives, landing pages, or client sites. This Actor gives teams a repeatable QA layer with explicit failure reasons instead of a vague pass/fail result.

### Key features

- Extracts Open Graph title, description, image, URL, type, and site name.
- Extracts Twitter/X card, title, description, image, and site metadata.
- Checks canonical-link presence.
- Optionally verifies whether the Open Graph image is reachable and served as an image.
- Flags missing fields, cross-domain `og:url`, unreachable images, and unusually long social text.
- Returns page title, meta description, HTTP status, issue count, and 0-100 score.
- Supports up to 100 public URLs per run with controlled concurrency.

### Input

```json
{
  "urls": ["https://www.python.org"],
  "verifyImages": true,
  "concurrency": 5
}
```

### Output

Each URL produces a structured record containing final URL, HTTP status, page metadata, Open Graph data, Twitter/X card data, canonical URL, optional image validation, issue list, issue count, and score.

### Example

```json
{
  "ok": true,
  "score": 82,
  "openGraph": {"title": "Example", "image": "https://example.com/preview.png"},
  "twitter": {"card": "summary_large_image"},
  "issues": ["canonical_missing"]
}
```

### Use cases

- Editorial and publishing QA
- E-commerce product-page checks
- Landing-page launch validation
- Social-sharing regression monitoring
- Agency audits across client websites
- CI-style metadata checks before releases

### Pricing

Pay per result. The current price is **$0.00075 per checked URL**, equivalent to **$0.75 per 1,000 results**.

### Limitations

- The score is a QA heuristic, not a guarantee of how every social platform will render a page.
- Some platforms cache previews independently; this Actor checks the current public page metadata.
- JavaScript-generated metadata may not be visible to a lightweight HTML request.
- WAFs, authentication, CAPTCHAs, or blocked image requests can affect validation.

### Responsible use

Only public HTTP/HTTPS pages are checked. Private-network destinations and unsafe redirects are blocked.

# Actor input Schema

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

Public HTTP/HTTPS URLs to validate.

## `verifyImages` (type: `boolean`):

Check whether og:image resolves to a reachable image response.

## `concurrency` (type: `integer`):

Parallel URL checks.

## Actor input object example

```json
{
  "urls": [
    "https://www.python.org"
  ],
  "verifyImages": true,
  "concurrency": 5
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("quanmatrix/social-preview-validator").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("quanmatrix/social-preview-validator").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 '{}' |
apify call quanmatrix/social-preview-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,quanmatrix/social-preview-validator"
        }
    }
}

```

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/i9xljMqzMxasQrfab/builds/mAqkPGUxgq61F9h5H/openapi.json