Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

A URL Preview API accepts an absolute web address and returns structured context—usually a title, description, image, domain or favicon, and canonical link—so your chat, sharing or bookmarking interface can show a useful preview before someone opens the page. Microsoft Project URL Preview v7 is one documented option, but its US-English scope and strict display and retention rules make provider selection as important as the HTTP request.

What a URL Preview API returns

Link-preview services fetch a URL, inspect its metadata and return fields your interface can render. Typical data includes:

  • Title or name from Open Graph, a title tag or provider-specific extraction.
  • Description suitable for a compact card.
  • Representative image, often an Open Graph image.
  • Canonical or source URL for attribution and the click target.
  • Domain, site name or favicon, depending on the service.
  • Safety or classification fields; Microsoft, for example, can return isFamilyFriendly.

The API does not make the destination safe by itself. Treat returned URLs and images as untrusted content, enforce your own moderation and rendering policy, and keep the source link visible.

Microsoft Project URL Preview v7: request and response

Microsoft documents this HTTPS endpoint:

https://api.labs.cognitive.microsoft.com/urlpreview/v7.0/search?q=queryURL

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
API Design Patterns
  • API Design Patterns
  • ABIS BOOK
  • Manning Publications

Send the absolute HTTP or HTTPS destination in the q query parameter and authenticate with the Ocp-Apim-Subscription-Key header. The documented maximum query URL length is 2,048 characters; Microsoft recommends keeping query parameters below 1,500 characters.

Minimal cURL request

curl -G "https://api.labs.cognitive.microsoft.com/urlpreview/v7.0/search" 
  -H "Ocp-Apim-Subscription-Key: $URL_PREVIEW_KEY" 
  --data-urlencode "q=https://example.com/article"

Use --data-urlencode rather than concatenating an unescaped URL. It correctly handles ampersands, spaces and non-ASCII characters inside the destination.

Python request

import os
import requests

url = "https://example.com/article"
response = requests.get(
    "https://api.labs.cognitive.microsoft.com/urlpreview/v7.0/search",
    params={"q": url},
    headers={"Ocp-Apim-Subscription-Key": os.environ["URL_PREVIEW_KEY"]},
    timeout=15,
)
response.raise_for_status()
preview = response.json()
print(preview)

Node.js request

const destination = "https://example.com/article";
const query = new URLSearchParams({ q: destination });
const response = await fetch(
  `https://api.labs.cognitive.microsoft.com/urlpreview/v7.0/search?${query}`,
  { headers: { "Ocp-Apim-Subscription-Key": process.env.URL_PREVIEW_KEY } }
);
if (!response.ok) throw new Error(`Preview failed: ${response.status}`);
const preview = await response.json();
console.log(preview);

Keep the subscription key on your server. A browser bundle, mobile binary or public repository can expose it and allow unauthorized use.

Build a source-linked preview flow

  1. Accept and validate input. Parse the value with a URL parser and allow only http: and https:. Reject credentials, unsupported schemes and malformed hosts before calling the provider.
  2. Normalize conservatively. Preserve meaningful query parameters, but remove fragments if your product does not need them. Do not silently change the destination shown to the user.
  3. Call the API from your backend. Apply a short timeout, bounded retries for transient failures and a response-size limit.
  4. Map fields to your own schema. Store only what your product is legally allowed to retain. Keep missing fields null rather than inventing text.
  5. Render defensively. Escape text, allow-list image protocols, constrain image dimensions and prevent HTML from being interpreted as markup.
  6. Make attribution obvious. The card, thumbnail and title should link to the returned source URL.
  7. Provide a fallback. If the request fails or has no image, show the URL and domain instead of a broken card.

Microsoft-specific usage limits

Microsoft says URL Preview data may be used only to display preview snippets and thumbnail images hyperlinked to their source sites in end-user-initiated URL sharing, such as social media or chat-bot experiences. It also says not to copy, store or cache data received from Project URL Preview, and that integrations must honor a site or content owner’s request to disable previews. These terms rule out a conventional permanent metadata cache: design your flow to fetch for the sharing event and discard the response according to Microsoft’s requirements.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The reference currently documents support for the United States and English only. If your users or content are elsewhere, test the behavior and consider a provider whose documented geography and language coverage matches your product. The documentation also notes that generic search headers such as Pragma and User-Agent do not change URL Preview behavior; some globalization parameters are reserved for possible future use.

Choosing an API for your product

Compare providers on the dimensions that affect the user experience and your legal design, not just the number of returned fields.

Service Documented characteristics Best fit and caution
Microsoft Project URL Preview v7 Resource name, description, family-friendly value, representative image and complete-resource link; HTTPS key authentication; US-English scope; no-copy/no-store/no-cache rule. End-user sharing previews where Microsoft’s terms and geography fit.
OpenGraph.io Open Graph, Twitter Cards and HTML meta tags; hybridGraph combines extracted data; documented cache control, JavaScript rendering, proxy options and retries. Its product page advertises Developer, Production and Enterprise credit plans. Applications needing richer extraction controls. Confirm current quotas, pricing and data-use terms before launch.
URLPreview.com GET endpoint for title, description, image, site name, favicon and related metadata; advertises JavaScript-heavy-site support and 1,000 requests per month on its free plan. Straightforward preview cards and prototypes; verify current limits and retention terms.
TryUnfurl POST /api/unfurl; returns Open Graph, Twitter Card, title, description, canonical URL and favicon; handles redirects, encoding, broken HTML and fallback from Open Graph to Twitter Card to basic HTML. Lightweight unfurling. It documents 30 no-account requests and 100 requests per day for a free account; paid Basic and Enterprise tiers are described as coming soon, so confirm production availability.

OpenGraph.io advertises 50,000 credits for Developer, 250,000 for Production and 1,000,000 for Enterprise. Those are advertised plan allocations, not a performance guarantee or an SLA. Across every provider, ask whether JavaScript executes, how redirects and bot checks are handled, what rate limits apply, which regions and languages work, and whether responses may be retained.

Metadata, JavaScript and fallback behavior

Static metadata

Many pages expose og:title, og:description, og:image, Twitter Card tags and a canonical link in initial HTML. A basic extractor is fast but may return little when a framework fills the page after load.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

JavaScript-rendered pages

Rendering a page in a browser can reveal client-generated metadata, but it costs more time and resources and introduces cookie banners, bot challenges and network failures. Confirm whether your chosen API renders JavaScript and whether that behavior is included in the plan.

Fallback order

A robust service can try Open Graph first, then Twitter Cards, then ordinary HTML title and description. If you implement your own fallback, mark inferred values internally so your UI does not present them as publisher-supplied facts.

Reliability, security and operations

  • Timeouts: Use a finite connect and total timeout. Do not let a slow destination block message delivery.
  • Retries: Retry only transient network errors and selected 5xx responses, with exponential backoff and a cap. Do not retry malformed URLs or authentication failures.
  • Redirects: Restrict redirect chains and revalidate the final scheme and host. Never allow a preview fetcher to reach internal IP ranges or cloud metadata endpoints.
  • SSRF controls: Resolve and filter private, loopback and link-local addresses at connection time, including after redirects.
  • Abuse limits: Rate-limit callers, cap URL length and limit concurrent fetches. Preview endpoints are attractive for scraping and denial-of-service attacks.
  • Images: Proxy or transform images only when your provider’s terms permit it. Validate content type and size; do not trust a file extension.
  • Observability: Record status, latency, provider error category and whether a fallback was shown. Avoid logging subscription keys or sensitive query strings.

Common failures and fixes

Symptom Likely cause Fix
401 or 403 Missing, mistyped or unauthorized subscription key. Load the server-side secret correctly, check the header name exactly and verify the subscription’s region and status.
400 response Missing q, malformed URL or excessive length. Require an absolute HTTP/HTTPS URL, URL-encode it and enforce the 2,048-character maximum.
Empty or sparse card Destination has no usable metadata, blocks fetching or renders content only in JavaScript. Show a URL-only fallback; choose a renderer or provider with documented JavaScript support when necessary.
Works in development, fails in production Client-side key exposure, firewall egress restrictions or different geography. Move calls to the backend, allow HTTPS egress and test from the deployment region.
Preview violates publisher wishes No opt-out handling. Honor explicit disable requests and remove the preview rather than repeatedly refetching it.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If you need a rendered screenshot as well as metadata, ScreenshotNeo is the first service to try: it removes cookie banners, newsletter popups and chat widgets before capture, bills only clean shots, and has the lowest paid plan described here.

One GET request returns an image or PDF. See the ScreenshotNeo documentation for all options.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Bot checks, blank pages and failed loads are never billed; response headers identify the page verdict and billing status. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Is a URL Preview API the same as a screenshot API?

No. A preview API returns structured metadata; a screenshot API renders pixels. They can complement each other in a link card or moderation workflow.

Should preview responses be cached?

Only when the provider’s terms allow it. Microsoft’s Project URL Preview documentation explicitly prohibits copying, storing or caching its returned data.

Can I call Microsoft Project URL Preview directly from a browser?

Keep the subscription key server-side. A backend endpoint protects the credential and lets you validate URLs and enforce SSRF controls.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

What should an international product check first?

Check documented geography and language coverage before implementing the card. Microsoft currently documents US-English support, which may not satisfy a global audience.

Frequently Asked Questions

How long should a preview request wait?

Set a finite total timeout appropriate to your interaction, then show a URL-only fallback when it expires rather than blocking the message or page.

What if a page has no Open Graph tags?

Use the provider’s documented fallback behavior or display a minimal card containing the destination URL and domain.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.