← Back to blog

Open Graph Preview API: Check Any URL's Social Tags

September 15, 2026 · Eric · 8 min read

You ship a landing page, paste the link into Slack, and the preview is a bare URL with no title and no image. The page itself renders perfectly, which is exactly why the problem hides so well: the card is built from <meta property="og:..."> tags that a crawler reads on its own, and nothing in your normal workflow ever looks at what the crawler sees.

Agent Media Tools has a free Open Graph preview endpoint that reads a public page server-side and returns every field a link unfurler cares about as flat JSON — Open Graph tags, Twitter Card tags, canonical, favicon, charset, language, H1, whether JSON-LD is present, and the resolved fallback title and description. It is the same endpoint behind the free Website Checkup page.

One GET request, every social field

The whole API is one query parameter. Inputs without a scheme get https:// prepended, so a bare domain works:

curl -s "https://agentmediatools.com/api/og-preview?url=example.com"

Real response, run against a page that has no social tags at all:

{"success":true,"og":{"url":"https://example.com/","status":200,"content_type":"text/html","title":"Example Domain","og_title":null,"og_description":null,"og_image":null,"og_type":null,"og_site_name":null,"twitter_title":null,"twitter_description":null,"twitter_image":null,"twitter_card":null,"description":null,"favicon":"data:,","charset":null,"lang":"en","h1":"Example Domain","canonical":null,"jsonld":false,"size_bytes":559,"best_title":"Example Domain","best_description":null}}

Note the shape: missing tags come back as null instead of being omitted. Your parsing code can rely on every key existing.

What each field is for

FieldMeaning
url, status, content_typeFinal URL actually fetched, its HTTP status, and the response content type
titleRaw <title> text
og_title, og_description, og_image, og_type, og_site_nameThe og:* tags. og_image is rewritten to an absolute URL when the page used a relative path
twitter_title, twitter_description, twitter_image, twitter_cardThe twitter:* tags, same absolute-URL treatment for images
descriptionPlain <meta name="description">
faviconrel="icon" target, resolved against the page origin
charset, langDeclared encoding and <html lang>
h1First H1 on the page
canonicalCanonical link target, verbatim
jsonldBoolean — does the page include an application/ld+json block
size_bytesLength of the fetched HTML body (see the truncation note below)
best_title, best_descriptionPre-resolved fallbacks — the fields most callers should read

The two fields you actually want

Link card renderers do not read a single tag; they walk a chain of fallbacks. This API pre-computes that chain for you:

In the sample above the page has no Open Graph tags whatsoever, so best_title fell back to the document title while best_description stayed null — there was nothing to fall back to. That is the difference between "my card looks plain" and "my card is empty", and it is visible in a single request.

Because the parser reads the raw HTML, values come back exactly as written in the attribute. HTML entities are not decoded: an ampersand in a title comes back as the entity text, not as a bare ampersand. On a real page:

title: Free Unit Conversion API for AI Agents (curl &amp; Python) — Agent Media Tools Blog

Run html.unescape() (or your language's equivalent) before you put a title in a UI, or the entity leaks into the preview.

Python: build a link card without branching

With requests, a title-and-image card is a few lines, and the fallback field removes the nested or chain:

import html
import requests

API = "https://agentmediatools.com/api/og-preview"
r = requests.get(API, params={"url": "https://agentmediatools.com/pricing"}, timeout=30)
r.raise_for_status()
og = r.json()["og"]

print(html.unescape(og["best_title"]))
print("status:", og["status"], "| image:", og["og_image"], "| card:", og["twitter_card"])

Real output from that script:

Pricing — Free, Founding Pro &amp; Teams | Agent Media Tools
status: 200 | image: https://agentmediatools.com/images/mira/mira-pricing.jpg | card: summary_large_image

Audit a list of pages before you publish

The more useful pattern is preflight: check a handful of URLs as part of a release, and fail loudly when a required tag is missing. Note the order of the checks — a fetch failure comes back as "success": false, so read that first:

import requests

API = "https://agentmediatools.com/api/og-preview"
PAGES = [
    "https://agentmediatools.com/",
    "https://this-domain-does-not-exist-amt-check.invalid",
]

for url in PAGES:
    data = requests.get(API, params={"url": url}, timeout=30).json()
    if not data.get("success"):
        print(f"{url} -> ERROR: {data['error']}")
        continue
    og = data["og"]
    problems = []
    if og["status"] != 200:
        problems.append(f"HTTP {og['status']}")
    for field in ("og_title", "og_description", "og_image", "canonical"):
        if not og[field]:
            problems.append(f"missing {field}")
    print(f"{url} -> {', '.join(problems) if problems else 'OK'}")
https://agentmediatools.com/ -> OK
https://this-domain-does-not-exist-amt-check.invalid -> ERROR: Fetch failed: getaddrinfo ENOTFOUND this-domain-does-not-exist-amt-check.invalid

One caveat that matters for batch jobs: every call counts against the shared free pool — 10 calls per day for anonymous IPs, 25 per day when signed in, and 1,000 per day on a Pro plan. A 200-URL audit is a plan-level job, not an anonymous one. The 429 response tells you which pool you hit (ANON_DAILY_LIMIT, FREE_USER_DAILY_LIMIT, AGENT_FREE_DAILY_LIMIT, or AGENT_PAID_DAILY_LIMIT) and returns the current limit and used counts alongside the pricing link, so a script can back off or stop cleanly instead of retrying blindly.

Check that your og:image actually resolves

The most common broken card is a valid tag pointing at a URL that 404s or serves HTML instead of an image. Because the endpoint fetches whatever URL you give it, you can point it at the image itself and read the content type:

curl -s "https://agentmediatools.com/api/og-preview?url=https://agentmediatools.com/images/og-blog.jpg"
{"success":true,"og":{"url":"https://agentmediatools.com/images/og-blog.jpg","status":200,"content_type":"image/jpeg","title":null,"og_title":null,"og_description":null,"og_image":null,"og_type":null,"og_site_name":null,"twitter_title":null,"twitter_description":null,"twitter_image":null,"twitter_card":null,"description":null,"favicon":null,"charset":null,"lang":null,"h1":null,"canonical":null,"jsonld":false,"size_bytes":50000,"best_title":null,"best_description":null}}

status: 200 plus content_type: image/jpeg is the check you want. One trap: size_bytes reported 50000 for that JPEG, which is not its real size. The fetcher truncates the body at 50,000 characters, so size_bytes is "bytes read", not "bytes served" — never use it to judge image weight. Use the image tools (resize, convert, compress) for that, and use this endpoint only to confirm the URL resolves and serves an image type.

What the endpoint does not do

Limits and authentication

CallerDaily calls
Anonymous (per IP, shared across the free tool API)10
Free account, signed in25
Free agent API key (mt_...)25
Pro plan1,000

No key is required to try it. To call it as an agent, send your key as a header on the same URL and the request is metered against that key instead of the anonymous IP pool:

curl -s -H "Authorization: Bearer mt_your_key_here" \
  "https://agentmediatools.com/api/og-preview?url=https://your-site.com"

Reaching the limit returns 429 with a JSON body containing the pool-specific code, the limit, how many you have used, and a link to pricing (plus a register link for the anonymous and signed-in pools) — enough for an agent to decide whether to back off or upgrade rather than guess.

The browser version: Website Checkup

If you would rather not write code, Website Checkup runs this same endpoint plus the SSL certificate checker and renders a printable page-health report: metadata, social preview fields, HTTPS status, and certificate expiry. It is free to run and useful as a client deliverable, and it is the same data you get from the API — just formatted.

Where this fits with the other page tools

Try it in the Toolbox

Paste any URL and see its social card fields instantly — or call the same endpoint from your agent with an API key.

Open toolbox