Social preview
See how a page looks when shared on social sites and chat apps, and which tags are missing.
GET /v1/social-preview
- Price
- Costs 1 credit per call; cached answers cost the same. Calls that fail upstream (502) are free.
- Cache
- Answers are cached for up to 15 minutes, per account except for a site's home page; send fresh=true to ask the source again.
- MCP tool
- check_social_preview
Query parameters
| Name | Type | Description |
|---|---|---|
| url (required) | string | A page URL or a domain; a domain means its home page. |
| fresh | boolean | Skip the cache and ask the source again; costs the same. |
Response
| Name | Type | Description |
|---|---|---|
| tool (required) | string | |
| target (required) | string | |
| status (required) | "ok" | "partial" | "error" | |
| fetched_at | string | |
| cached | boolean | |
| credits_used | integer | Credits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in |
| summary (required) | string | |
| score | integer or null | |
| findings | array of object | |
| credits_remaining (required) | integer | Your balance after this call. It can be below zero after a refund; free tools still work then |
| data (required) | object | This tool's result |
| data.url (required) | string | |
| data.final_url (required) | string or null | |
| data.og (required) | object | |
| data.twitter (required) | object | |
| data.resolved (required) | object | |
| data.resolved.title (required) | string or null | |
| data.resolved.description (required) | string or null | |
| data.resolved.image (required) | string or null | |
| data.resolved.url (required) | string or null | |
| data.resolved.type (required) | string or null | |
| data.resolved.site_name (required) | string or null | |
| data.resolved.twitter_card (required) | string or null | |
| data.resolved.twitter_site (required) | string or null | |
| data.resolved.sources (required) | object | |
| data.image (required) | object or null | |
| data.platforms (required) | array of "linkedin" | "x" | "facebook" | "slack" | "whatsapp" | |
| data.refresh_tools (required) | object |
Errors
- 400 Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- 401 Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- 402 Balance below the call's price (`insufficient_credits`)
- 403 Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- 429 Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- 500 Unexpected error (`internal_error`)
- 502 Every upstream source failed; not charged (`source_unavailable`). A Retry-After header says how long to wait when the source asked us to
- 503 Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged
Example
curl
curl "https://api.dnssuper.com/v1/social-preview?url=example.com" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"Python
import os
import httpx
client = httpx.Client(
base_url="https://api.dnssuper.com",
headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
timeout=60,
)
response = client.get("/v1/social-preview", params={
"url": "example.com",
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])TypeScript
const response = await fetch(`https://api.dnssuper.com/v1/social-preview?${new URLSearchParams({"url":"example.com"})}`, {
headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);Example response
{
"tool": "social-preview",
"target": "https://example.com/",
"status": "ok",
"fetched_at": "2026-11-14T10:00:00Z",
"cached": false,
"credits_used": 1,
"summary": "Links to example.com show a full preview: a title, a description and a 1200 x 630 image.",
"findings": [],
"data": {
"url": "https://example.com/",
"final_url": "https://example.com/",
"og": {
"og:title": [
"Example Widgets"
],
"og:description": [
"Widgets for every workshop, shipped worldwide."
],
"og:image": [
"https://cdn.example.net/images/card.png"
],
"og:url": [
"https://example.com/"
],
"og:type": [
"website"
],
"og:site_name": [
"Example"
]
},
"twitter": {
"twitter:card": [
"summary_large_image"
],
"twitter:site": [
"@example"
]
},
"resolved": {
"title": "Example Widgets",
"description": "Widgets for every workshop, shipped worldwide.",
"image": "https://cdn.example.net/images/card.png",
"url": "https://example.com/",
"type": "website",
"site_name": "Example",
"twitter_card": "summary_large_image",
"twitter_site": "@example",
"sources": {
"title": "og",
"description": "og",
"image": "og"
}
},
"image": {
"url": "https://cdn.example.net/images/card.png",
"status": 200,
"info": {
"format": "png",
"width": 1200,
"height": 630,
"bytes": 3176,
"content_type": "image/png",
"type_matches": true,
"animated": false
},
"https": true,
"absolute": true,
"preview": "data:image/webp;base64,UklGRk4DAABXRUJQVlA4IEIDAACwQQCdASpYAjsBPm02mEkkIqKhIAmogA2JaW7hdoH+9gJvAkjyQQBLf/P/MSv8A6f831ir/gB6IBYKU4u7FkkkrxNAkKp8ksOTENbDkn9MU3W3zp8Y71WI9p81zm48RTd3bAoBjp1XZiHzElGT8c2H45r7EheMmleNSmVuTf+YkH5le5krd1vTqt05OqfjmvsV/cHB1s5qlmJGPfrjbjUMadYVdmIfMSUeC8Gm1PbhZeTJp1S3nb5GIq/5iQfmVyQsuNuNQxp2DIAg02p7cLLn62c1SzEjNWyINkrd1PU7sWVFT8c19iQvGTSvGpTK3Jv/MSD8yvcyVu63p1W6cnVPxzX2K/uDg62c1SzEjHv1xtxqGNOsKuzEPmJKPBeDTantwsvJk06pbzt8jEVf8xIPzK97Cbu7v1xtDv3yMQ+gEGmm8B2H45r7Ff3BwdbOapZiRj364241DGnWFXZiHzElHgvBptT24WXkyadUt52+RiKv+YkH5le9hN3d3642h375GIfQCDTTeA7D8c19iv7g4OtnNUsxIx79cbcahjTrCrsxD5iSjwXg02p7cLLyZNOqW87fIxFX/MSD8yvewm7u79cbQ798jEPoBBppvAdh+Oa+xX9wcHWzmqWYkY9+uNuNQxp1hV2Yh8xJR4LwabU9uFl5MmnVLedvkYir/mJB+ZXvYTd3d+uNod++RiH0Ag003gOw9AAA/t4jGspmP//46v37yvf+z49//+hHez3HE1QQA3dgz/W36ve8itKCtCmm3jp91mNiNR6c71QB/3N3D+8px9WM/p+rqvZp7eCt7Dw8qkFyu8U6OblqUNLOntYv0hPvxb7Ev1t+r3yji98fPIGEi6+29pneqAMnAhFEkwrl9sOv1GjEGuDvV/TFKjCuTpBfFMJuJsttJAZe2kMI0R3EINIIDLbfXhECvdfzOwtUx2q5F3wZa+Uo24P8Lgq8yqfdG3IzhcDMrJQboPp98XdKNuRnC4GZrDUIFfkgnT40bcjOFwMzWGoQK/JBOnxo25GcLgZmsNQgV+SCdPjRtyM4XAzNYahAr8kE6fGjbkZwuBmaw1CBX5IJ0+NG3IzhcDM1hqECvyQTp8aNuRnAgAA=",
"ratio": 1.9
},
"platforms": [
"linkedin",
"x",
"facebook",
"slack",
"whatsapp"
],
"refresh_tools": {
"linkedin": "https://www.linkedin.com/post-inspector/",
"facebook": "https://developers.facebook.com/tools/debug/"
}
},
"credits_remaining": 498
}MCP
{
"tool": "check_social_preview",
"arguments": {
"url": "example.com"
}
}Links to example.com show a full preview: a title, a description and a 1200 x 630 image.
Title (og): Example Widgets
Description (og): Widgets for every workshop, shipped worldwide.
Image (og): https://cdn.example.net/images/card.png, 1200 x 630 png
Preview copy: 600x315 WebP
X card: summary_large_image
Shows an image on: LinkedIn, X, Facebook, Slack, WhatsApp
Refresh: linkedin https://www.linkedin.com/post-inspector/; facebook https://developers.facebook.com/tools/debug/
No issues found.
Credits: 1 credit used, 498 remaining | fresh | checked 2026-11-14 10:00 UTC