1. Home
2. Products
3. Social card preview
4. API

Open Graph API

A plain JSON endpoint that reads any URL’s Open Graph and Twitter card tags — title, description, image (fetched and validated, with dimensions) and a checklist of what’s missing or off. Built for scripts, CI checks and AI agents. Free, no key, CORS-enabled.

Endpoint

And one for checking your own allowance, which does not count against it:

Machine-readable: OpenAPI 3.1 describes every parameter, all 21 error codes with their retryability, and the 87 stable check ids — and /llms.txt is the short version. There is a Postman collection to import, and a requests.http that VS Code's REST Client and the JetBrains HTTP client both run as they are. All four are generated from the same source as this page, so a parameter cannot exist in one and not the others.

Parameters

Example

That is the whole response, verbatim — not an abridged one. example.com carries almost no card tags, which is why the checks do the talking and why most fields come back empty. A fully-tagged page fills in siteName, card, imageUrl and the image dimensions, and splits views wherever two platforms would not see the same card.

Response

Always HTTP 200 with a JSON body. Check the ok field, not the status code (see Errors & limits).

checks

Each entry is { "level": …, "id": …, "message": … }.

Key off id, never off message. The id names the condition and is stable; the message is prose and gets rewritten whenever we find a clearer or more accurate way to say it. In September 2026 four messages changed in one afternoon, because they were claiming more than the tool had measured — anything matching on their text would have quietly stopped matching. Ids are added when checks are added, and a rename is treated as a breaking change.

level is the severity:

The thresholds are grounded in the Open Graph protocol (which tags are required vs optional) and the platform docs (Facebook, X’s Cards, LinkedIn) for sizes and truncation — then sanity-checked against a corpus of real sites, so well-built pages stay quiet and only genuine problems flag.

Several pages in one request

Repeat url to check up to five pages at once. Each page counts as one request against your allowance, and a page listed twice is checked and counted once. The pages are fetched concurrently, so the answer takes as long as the slowest of them.

The answer is {"ok": true, "batch": true, "count": 2, "results": […]}. Each entry in results is what a request for that page alone would return, with its own ok, code, retryable and checks, plus the url as you sent it, in the order you sent them. The top-level ok says the request was understood; each result’s ok is about its page.

• More than five url values are refused whole with too_many_urls, and nothing is checked.
• With site, url is ignored.
• URL-encode every value. A literal & or + in a page’s address otherwise splits or changes it.
• A batch is cached as one answer for its list of pages, and not at all if any page in it would not be.

Gating a build on it

Every response is HTTP 200, so a gate reads the body. This one fails a build on anything that will visibly break the card:

Test ok before reaching for checks. A refusal carries no checks at all — a URL that will not parse, a host that refuses crawlers, or your allowance gone answers ok: false with a code and nothing else. A gate that goes straight to .checks dies on Cannot iterate over null, which fails the build for a reason nobody reading the log can act on. Both recipes here test ok first, and name the code when they stop.

Two gates are stable: level == "error", and a list of check ids you name yourself. Gating on every warn is a third option with a cost worth knowing. New checks arrive at warn or tip, so one of ours can turn your build red on our release schedule; every addition is logged in the change log below, so it never arrives unannounced.

For text length, gate on the number. description.long fires at 200 characters, which is the one limit with a primary source. Most cards clamp the description to two lines and stop well before that, at a width and a font this API never sees, so pick the budget your own design needs:

Give CI an allowance it will not run out of

The anonymous allowance is 500 requests a day and it is counted per network address, which a build server shares across every job on it. A repository running twenty pull requests a day over thirty URLs passes that before lunch. A gate that starts failing when the allowance runs out is worse than no gate, because it fails on a day when nothing was wrong and teaches everyone to re-run it.

So identify the build. A free key raises it to 5,000 a day; sending an x-og-contact header raises it to 2,000 with no key and no signup. quota_exceeded is marked retryable for the same reason: it means the check did not run, not that the card is broken, and CI should say so rather than failing the change under review.

Errors & limits

• Two exceptions to the 200 rule, and neither is ours. A shared burst limit of 10 requests a second (bursting to 20) sits in front of this API; exceeding it returns HTTP 429 from the gateway with a plain {"message":"Too Many Requests"}. Under extreme load the compute layer can also answer HTTP 503 with {"message":"Service Unavailable"}. Neither carries an ok field, and both are worth retrying after a moment. Everything below concerns the API itself.
• Application errors (bad URL, unreachable host, blocked address) return HTTP 200 with { "ok": false, "error": "…" } — so a single check is enough; you needn’t branch on status codes.
• Rate limiting. A shared burst limit of 10 requests/second, plus a daily allowance per caller: 500 requests a day anonymously, 2,000 if you identify yourself, or 5,000 with a free API key — both below. Over the allowance you get ok: false with an explanation, and a rejection carries x-ratelimit-limit and x-ratelimit-remaining as counts, and retry-after and x-ratelimit-reset as seconds to the next reset at midnight UTC, so a script knows how long to wait. The same three numbers are in the body as limit, remaining and resetSeconds. They ride on a rejection only: a card is cached and shared between callers, so a remaining count attached to one would be served to the next. Responses are cached ~5 minutes per URL, so repeat calls of the same URL are free. The exception is a URL on a platform’s own site, or one that redirects there: that answer depends on your key, so it is never cached.
• Identifying yourself — optional, no signup. Send an x-og-contact header (or &contact=) with an email or a URL and your daily allowance goes up to 2,000. No key, no account: it just gives us a way to reach you.
• An API key — free, for a bigger allowance. 5,000 requests a day, counted against the key rather than your IP address. How to get one.
• Some sites can’t be read at all. A few gate every unauthenticated fetch, so no crawler — ours or a real platform’s — can see a card. Reddit is the current example: those return ok: false immediately with the reason, rather than making you wait for a timeout.
• SSRF-guarded. It won’t fetch private, loopback, link-local or cloud-metadata addresses, and re-checks every redirect hop.
• CORS. Access-Control-Allow-Origin: * — callable straight from browser JavaScript.

Every error code

Generated from the handler itself, so this list cannot drift from what the API returns — it previously named two codes that did not exist and omitted four that did. Retryable means the same request could succeed later; everything else is permanent as written.

Checking your allowance

GET /og/quota answers with today’s usage for whoever is asking. Send the same x-og-contact or x-og-key header you would send with a request and it reports the allowance that header earns you. Asking does not spend a request, so a script can check once a run rather than discovering the limit by hitting it.

The same three numbers come back as x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers. This endpoint is never cached — the answer depends entirely on who is asking — which is also why those headers appear here and on a refusal, but not on a successful card: cards are cached and shared between callers, so a remaining count attached to one would be handed to the next.

Every check id

All 87, grouped by the level they report at. Ids are stable and a rename is treated as a breaking change; the messages beside them are not, and are rewritten whenever a clearer or more accurate wording is found. Each problem id links to its reference page: when it is raised and how to fix it.

When this changes

Your gate is probably “no checks at level error”. So a new check arriving at error, or an existing one promoted to it, would turn your builds red on our release schedule — with no id removed and no field retyped. That is a breaking change from where you are sitting, and it is the one a version number alone never warns you about.

• New checks land at warn or tip. Never at error.
• Raising a check to error is breaking, and is announced before it ships.
• So is removing or renaming a check id, removing or retyping a response field, or removing an error code.
• Adding a check at warn, or a new response field, is not.

changes.json carries the dated log and the current inventory as {id, level} — diff it against the ids you gate on. Every response carries specVersion, and specNext when a breaking change is scheduled.

Don’t pin specVersion in CI. Every ordinary release would fail your build on our schedule. Log it, and surface specNext as a warning instead:

How it works

It fetches the page and reads its Open Graph and Twitter-card tags — title, description, image — then fetches the image itself to check it really exists and what shape it is. The checklist flags what’s missing or off: no image, a title that’ll truncate, an image that’s too small or the wrong shape. The preview tool renders the same data as a card at three sizes: large, compact, and the small thumbnail most feeds use.

Tips

• Use a 1200×630 image (1.91:1).
• Keep the title short — it has to read at thumbnail size.
• Set a per-page image, not one site-wide default.
• Re-scrape after changes. Facebook documents a 24-hour cache; LinkedIn publishes no figure.

Get a free key

Keys are free and raise the allowance to 5,000 requests a day. Send yours as an x-og-key header. Unlike the contact header, a key is counted against the key rather than your IP address — so the allowance follows you across machines, containers and CI runners rather than resetting with every new one.

To get one, email enquiries@poly.io and say roughly what you’re building. Issuance is manual on purpose: a person reads it, which is also your chance to say if the API is missing something you need. Need more than 5,000 a day? Say so and we’ll talk.

We store a label, the contact address you give us, and a one-way hash of the key — never the key itself, so we cannot tell you what it was if you lose it. Ask us and we’ll revoke it; we may also revoke one that’s being abused. What we keep and why.