Docs menu

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

Run it in the browser

Query parameters

Query parameters
NameTypeDescription
url (required)stringA page URL or a domain; a domain means its home page.
freshbooleanSkip the cache and ask the source again; costs the same.

Response

Response fields
NameTypeDescription
tool (required)string
target (required)string
status (required)"ok" | "partial" | "error"
fetched_atstring
cachedboolean
credits_usedintegerCredits 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
scoreinteger or null
findingsarray of object
credits_remaining (required)integerYour balance after this call. It can be below zero after a refund; free tools still work then
data (required)objectThis 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
curl "https://api.dnssuper.com/v1/social-preview?url=example.com" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"

Python

Python (httpx)
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

TypeScript (fetch)
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
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

MCP tool call
{
  "tool": "check_social_preview",
  "arguments": {
    "url": "example.com"
  }
}
Compact MCP output
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