Twitter Card Metadata Validator

Validate Twitter Card metadata across public web pages and export deterministic diagnostics for website QA. This Twitter Card validator fetches each supplied URL, extracts twitter:* and Open Graph tags, resolves the values X can use, and explains missing, invalid, duplicate, or likely truncated fields.

It returns one structured row per URL, including fetch failures. Use the rows in scheduled Tasks, CI checks, spreadsheets, dashboards, or regression comparisons without manually opening a browser validator for every release page.

What does Twitter Card Metadata Validator do?

For every unique input URL, the Actor:

1. fetches server-rendered public HTML;
2. follows up to five public redirects safely;
3. extracts all twitter:* and og:* meta values;
4. chooses explicit Twitter values before documented Open Graph fallbacks;
5. resolves relative image references against the final page URL;
6. validates card type, required fields, URLs, account handles, duplicates, and common length risks;
7. emits stable diagnostic codes and human-readable remediation messages.

This is metadata validation, not a screenshot of X's live composer. Rendering can change on X, while the Actor reports the page data available to a card consumer at check time.

Who is it for?

• Developers checking social metadata before and after releases.
• SEO teams auditing templates across landing pages and articles.
• Content teams finding pages with missing social titles, descriptions, or images.
• QA engineers comparing stable error codes between deployments.
• Agencies exporting repeatable client-site audit evidence.
• Platform teams monitoring metadata regressions with scheduled Apify Tasks.

Why use structured validation?

A visual preview alone is difficult to compare at scale. The dataset exposes both effective values and their source tags, so you can tell whether a title came from twitter:title, og:title, or the HTML <title>.

Unlike a generic meta-tag dump, each record includes:

• an overall isValid result;
• error and warning counts;
• stable machine-readable diagnostic codes;
• fallback source attribution;
• optional raw tags for exact regression diffs;
• a free diagnostic row when a site cannot be fetched.

Supported Twitter Card checks

The Actor recognizes summary, summary_large_image, player, and app card types. It reports an error for unknown types.

When twitter:card is absent but Open Graph card fields exist, the Actor infers summary and emits CARD_TYPE_INFERRED as a warning. It checks title availability, description and image presence, invalid image URLs, repeated or empty tags, likely title or description truncation, malformed twitter:site and twitter:creator handles, and required player-card fields.

A warning highlights a quality or portability risk. An error means the computed card fails a core validation rule. isValid is true only when there are no error-severity diagnostics.

Extracted Twitter Card data

Field	Meaning
requestedUrl	Original input URL
finalUrl	URL after redirects
fetched	Whether HTML was fetched and parsed
statusCode	Final HTTP status
cardType	Explicit or inferred card type
cardTypeSource	twitter or inferred
isValid	Whether no error diagnostic exists
errorCount / warningCount	Fast audit totals
effective	Resolved title, description, image, alt text, site, and creator
valueSources	Exact tag selected for each effective value
diagnostics	Stable code, severity, field, and message objects
rawTags	All Twitter/Open Graph values when enabled
checkedAt	UTC validation timestamp

How to validate Twitter Card metadata

1. Open the Actor in Apify Console.
2. Add one or more public page URLs under Web pages to validate.
3. Keep raw tags enabled when you need exact before/after comparisons.
4. Set a page limit and conservative concurrency for the target sites.
5. Click Start.
6. Inspect the default dataset's overview table.
7. Filter isValid = false, or export diagnostics to your QA pipeline.

The default input audits real Apify SDK project pages and produces useful output immediately.

Input parameters

Input	Type	Default	Notes
startUrls	URL array	required	Public HTTP(S) pages; duplicates run once
maxItems	integer	20	Maximum unique pages, from 1 to 1,000
maxConcurrency	integer	5	Parallel fetches, from 1 to 20
requestTimeoutSecs	integer	30	Per-attempt timeout, from 5 to 120 seconds
maxRetries	integer	2	Transient retries, from 0 to 3
includeRawTags	boolean	true	Include all discovered Twitter and Open Graph tags

Localhost, private-network addresses, credentials embedded in URLs, and non-HTTP protocols are blocked. Each redirect destination is checked again.

Output example

A current run against https://apify.com produces the following shape (long raw-tag values shortened here):

{
  "requestedUrl": "https://apify.com",
  "finalUrl": "https://apify.com/",
  "fetched": true,
  "statusCode": 200,
  "contentType": "text/html",
  "cardType": "summary_large_image",
  "cardTypeSource": "twitter",
  "isValid": true,
  "errorCount": 0,
  "warningCount": 0,
  "effective": {
    "title": "Apify: The largest marketplace of trusted tools for AI",
    "description": "Discover and use cloud tools for web data and automation.",
    "image": "https://apify.com/og-image.png",
    "imageAlt": null,
    "site": "@apify",
    "creator": null
  },
  "valueSources": {
    "title": "twitter:title",
    "description": "twitter:description",
    "image": "twitter:image",
    "imageAlt": null,
    "site": "twitter:site",
    "creator": null
  },
  "diagnostics": [],
  "checkedAt": "2026-09-06T12:00:00.000Z"
}

Exact content belongs to the target page and can change between runs. Use the dataset schema rather than hard-coding sample text.

How much does it cost to validate Twitter Card metadata?

Pay-per-event pricing combines a $0.001 start fee with one page event for each successfully fetched page. Failed fetches still produce a diagnostic row but have no page event charge.

Current page-event tiers are:

Apify plan	Price per fetched page
FREE	$0.00276
BRONZE	$0.0024
SILVER	$0.001872
GOLD	$0.00144
PLATINUM	$0.00144
DIAMOND	$0.00144

At BRONZE, 10 successfully fetched pages cost about $0.025 including the start fee, 100 cost about $0.241, and 1,000 cost about $2.401. Actual total depends on how many input pages fetch successfully. Retries do not create extra page charges.

Schedule metadata regression monitoring

Create an Apify Task with the pages in one release surface, then schedule it after deployments or once per day. Keep includeRawTags enabled when exact tag-level diffs matter, or disable it for smaller audit records.

Useful automation patterns include:

• alert when a row changes from valid to invalid;
• compare diagnostics[].code against the previous dataset;
• require effective.image on campaign landing pages;
• track which templates rely on Open Graph fallback;
• export failed URLs to a developer backlog.

The Actor does not send alerts or retain a historical diff itself. Connect scheduled run output to your preferred automation or storage system.

Export and integration options

The default dataset works with JSON, CSV, Excel, XML, RSS, and API clients supported by Apify. Nested objects are most expressive in JSON.

You can connect runs to:

• Google Sheets for editorial review;
• webhooks for CI or incident automation;
• Make or Zapier for notifications;
• a warehouse for longitudinal audits;
• another Actor for remediation triage.

Each input URL has a result row even when fetching fails, which makes batch accounting deterministic.

Run through the Apify API with cURL

Replace YOUR_TOKEN with an Apify API token:

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~twitter-card-metadata-validator/runs?token=YOUR_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{
    "startUrls": [
      {"url": "https://apify.com"},
      {"url": "https://github.com/apify/apify-sdk-js"}
    ],
    "maxItems": 2,
    "includeRawTags": true
  }'

Read the run's defaultDatasetId, then fetch its items through the dataset API.

Run with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/twitter-card-metadata-validator').call({
  startUrls: [{ url: 'https://apify.com' }],
  maxItems: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].isValid, items[0].diagnostics);

Run with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/twitter-card-metadata-validator').call(run_input={
    'startUrls': [{'url': 'https://apify.com'}],
    'maxItems': 1,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items[0]['isValid'], items[0]['diagnostics'])

Use with MCP and AI agents

Claude Code setup

Add the Apify MCP server to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/twitter-card-metadata-validator"

Claude Desktop, Cursor, and VS Code setup

Claude Desktop, Cursor, and VS Code can use the equivalent HTTP MCP configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/twitter-card-metadata-validator"
    }
  }
}

Example prompts:

• “Validate the Twitter Card metadata on these five release URLs and summarize errors by code.”
• “Run the validator for our landing pages and list pages relying on Open Graph fallback.”
• “Compare these result rows with yesterday's export and flag new missing images.”

Limits and failure behavior

The Actor reads server-rendered HTML and does not execute client-side JavaScript. Metadata injected only after browser rendering will appear missing. Login-protected pages, robots or firewall restrictions, rate limits, and bot challenges may prevent a fetch.

A page-level failure becomes a typed FETCH_FAILED dataset row and is not charged as a page event. Other pages continue. An invalid or empty top-level input fails the run. Responses above 5 MB, non-HTML responses, private destinations, and more than five redirects are rejected for safety.

Retries apply only to network failures, rate limits, and temporary server errors. Increasing retries can improve resilience but does not bypass authentication or stable access denial.

Legality and responsible use

Only submit URLs you are authorized to access and audit. Respect site terms, robots policies, rate limits, copyright, privacy obligations, and applicable law. The Actor accesses anonymously public metadata and does not bypass logins or collect private account data.

Metadata validation is technical assistance, not a guarantee that X will display a card. Social platforms can cache prior metadata, apply their own policies, crop images, or suppress previews.

Troubleshooting and FAQ

Why does a page return FETCH_FAILED?

Check the diagnostic message. The page may reject automated HTTP clients, require login, return non-HTML content, time out, or redirect to a private/non-public host. Test the final public URL and lower concurrency for fragile sites.

Why is twitter:card missing but cardType is summary?

Open Graph title, description, or image tags allow a summary-card fallback. The Actor records cardTypeSource: "inferred" and emits CARD_TYPE_INFERRED so you can choose whether to add an explicit tag.

Does the Actor verify the image can be downloaded?

No. It validates and resolves the image URL syntax but does not download media. This keeps runs fast and avoids unexpected transfer costs.

Does it show the exact visual Twitter Card preview?

No. It computes effective metadata fields and diagnostics. X controls final rendering, caching, cropping, and policy decisions.

Can I compare runs automatically?

Yes. Schedule a Task and compare isValid, counts, effective fields, diagnostic codes, or raw tags in your integration. Historical diffing is intentionally left to your workflow.

Are redirects supported?

Yes, up to five. Every redirect target must resolve exclusively to public IP addresses.

Related automation-lab Actors

For broader page quality work, use Multi-page On-page SEO Audit Crawler to crawl bounded websites and export titles, descriptions, headings, canonical tags, indexability, links, and deterministic SEO issues.

Use this Actor when the buyer job is specifically Twitter Card and Open Graph fallback validation for supplied URLs; use the broader crawler when page discovery and general on-page SEO signals are required.

Versioning

The dataset contract uses stable camelCase fields and machine-readable diagnostic codes. New optional checks may add diagnostic codes or nullable fields in later releases. Pin Actor versions in strict integrations and review the changelog before upgrading.