To use the LinkPreview API, send the page URL in the q parameter to https://api.linkpreview.net, authenticate with the X-Linkpreview-Api-Key header, then validate the JSON response before displaying its metadata. Keep the request on your server, expect missing fields and cached results, and handle documented HTTP errors such as 401, 403, 423, 429, and 503.
What the LinkPreview API does
LinkPreview fetches a publicly accessible page and extracts metadata suitable for a URL card: a title, description, preview image, and URL. The official documentation supports both GET and POST requests. The default response fields are title, description, image, and url. Optional fields include canonical URL, locale, site name, image dimensions, image size and MIME type, favicon URL and its dimensions, size, and MIME type. Availability of additional fields depends on your subscription.
It is an extraction service, not a browser-rendering guarantee. Login pages, paywalls, CAPTCHA and bot protection, JavaScript-only metadata, IP restrictions, deep links, missing tags, temporary network failures, and a site’s robots.txt policy can all produce incomplete data or an error. LinkPreview identifies its crawler as LinkPreview/1.6 and respects robots.txt; its documentation says it cannot guarantee correct data for every URL.
Before you make a request
Create and protect an API key
Create a key through the official LinkPreview service and documentation flow. Send it in the X-Linkpreview-Api-Key request header. The documentation marks the older key query parameter as deprecated. For a browser product, put the call in a server-side application so visitors cannot copy the key from JavaScript, and so your server can enforce authentication, quotas, caching, and abuse controls.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
Choose the URL and fields
The destination is passed as q. A GET query string must URL-encode reserved characters; use your HTTP library’s parameter encoder rather than concatenating an untrusted URL. Request only the fields your card needs. Extra fields can be plan-dependent, so confirm that your subscription includes them before making them mandatory in your schema.
Minimal GET request with cURL
This is the documented request shape:
curl "https://api.linkpreview.net/?q=https%3A%2F%2Fexample.com"
-H "X-Linkpreview-Api-Key: YOUR_API_KEY"In production, substitute a URL-encoded value for q and load the key from a secret store or environment variable. The command illustrates the endpoint and header; always check the returned HTTP status before parsing the body.
POST requests and application code
POST is also supported and can be preferable when your client already sends a JSON or form body. The following examples use GET with parameter encoding, which keeps the request close to the quick start while avoiding unsafe string concatenation.
Python
import os
import requests
api_key = os.environ["LINKPREVIEW_API_KEY"]
target = "https://example.com/article"
response = requests.get(
"https://api.linkpreview.net/",
params={"q": target},
headers={"X-Linkpreview-Api-Key": api_key},
timeout=30,
)
response.raise_for_status()
data = response.json()
preview = {
"title": data.get("title") or "",
"description": data.get("description") or "",
"image": data.get("image") or "",
"url": data.get("url") or target,
}
print(preview)Keep the timeout finite, catch request and JSON exceptions in the surrounding application, and treat an empty string as unavailable metadata rather than as proof that the page has no content.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Node.js
const apiKey = process.env.LINKPREVIEW_API_KEY;
const target = 'https://example.com/article';
const params = new URLSearchParams({ q: target });
const response = await fetch(`https://api.linkpreview.net/?${params}`, {
headers: { 'X-Linkpreview-Api-Key': apiKey },
});
if (!response.ok) {
throw new Error(`LinkPreview returned HTTP ${response.status}`);
}
const data = await response.json();
const preview = {
title: data.title || '',
description: data.description || '',
image: data.image || '',
url: data.url || target,
};
console.log(preview);Use the equivalent POST form supported by the documentation if your infrastructure prefers request bodies. Never expose LINKPREVIEW_API_KEY in a public bundle.
Rank #2
- Used Book in Good Condition
Parse and safely display the response
Validate the HTTP response first
Do not assume a 2xx response or valid JSON. Record the status, parse only a body you can handle, and return a safe fallback card when extraction is incomplete. Apply output encoding appropriate to your template engine; a title or description is untrusted remote text.
Handle blank and optional values
The documentation describes blank-string defaults when a string cannot be extracted and zero defaults for unavailable numeric fields. Your schema should therefore distinguish “field unavailable” from a real value. A practical card can omit an image when image is blank, use the requested URL as a fallback label, and avoid rendering zero dimensions as meaningful measurements.
Request additional fields deliberately
Use the comma-separated fields parameter for optional metadata only when your plan supports it. Examples include canonical URL, locale, site name, favicon information, image dimensions, image size, and MIME type. Keep your parser tolerant: an optional field may be absent even when the request succeeds.
Images: validation, proxying, and privacy
LinkPreview documents returned images in JPEG, PNG, GIF, ICO, and WebP formats up to 5 MB. When image validation matters, request image_size and check the reported dimensions or size before displaying or downloading the asset. Do not trust a URL merely because it ends in an image extension; apply your own content-type, size, and download limits.
The documentation recommends proxying and caching preview images through your secure environment so the original image host does not receive end-user IP addresses. A proxy also gives you one place to enforce maximum bytes, allowed MIME types, timeouts, and malware scanning. Cache by a normalized target URL and invalidate or refresh according to your product’s freshness needs.
Caching and freshness
LinkPreview caches requested pages. The exact cache period depends on unspecified factors and can take up to a day to expire, according to the documentation. Consequently, a publisher changing its title or image may not see that change in the next API response. Store the response you receive, show a refresh state when appropriate, and do not promise real-time metadata to users.
Your own cache should be separate from LinkPreview’s cache. A short application TTL reduces repeated API calls, while a manual refresh option can let editors request a new lookup when a card is clearly stale. Respect the service’s per-domain and account limits when implementing refresh buttons or bulk imports.
Recommended Free Tools
Errors and the correct response to each
| HTTP status | Documented meaning | Implementation response |
|---|---|---|
| 400 | Generic error | Log request context safely, validate the URL and parameters, and return a recoverable card error. |
| 401 | API access key cannot be verified | Check the secret, header spelling, environment, and key status; do not retry unchanged credentials. |
| 403 | Invalid or blank key | Fix configuration and prevent the request from reaching production with an empty secret. |
| 423 | Requested website disallows access through robots.txt |
Tell the user the target cannot be fetched by this service; do not try to bypass the policy. |
| 424 | Content blocked as potentially malicious or adult when block_content=true |
Show a policy-specific fallback and record the decision without exposing unsafe content. |
| 425 | Invalid response status from the remote server | Retry only under a bounded policy; preserve the target URL for later review. |
| 426 | Too many requests per second on one domain | Queue and space requests for that host; do not increase concurrency. |
| 429 | API rate limit exceeded | Apply exponential backoff, honor any retry guidance, and move work to a queue. |
| 503 | May occur during sudden bursts; temporary upstream bans are also possible | Reduce burst size, retry with jitter, and surface a temporary-unavailable state. |
LinkPreview documents a general maximum of one request per second to a single domain to protect smaller sites, with exceptions for named high-throughput domains. Treat that as a service policy, not a guarantee for every domain or plan; contact the service if you need a higher limit.
Why a title or image is missing
- The page requires login, a paywall, CAPTCHA, bot verification, or an allow-listed IP.
- Metadata is inserted only after JavaScript executes, while the parser receives the initial HTML.
- The site omits Open Graph or other recognizable metadata, or supplies malformed tags.
- The URL is a deep link that the remote server rejects, redirects unexpectedly, or returns a temporary error for.
robots.txtprevents the crawler from accessing the page.- The result is still in LinkPreview’s cache and has not reached the documented expiry window.
Design the card to work without an image or description. A missing field is a normal operating condition, not a reason to discard the entire URL.
Plans, quotas, and choosing an integration
The service homepage currently lists these plans; prices and terms can change, so verify them at purchase:
| Plan | Listed price | Quota | Use and listed capabilities |
|---|---|---|---|
| Free | $0/month | 60 requests per hour | Personal use |
| Basic | $8/month | 200 requests per hour | Personal use |
| Pro | $25/month | 1,000 requests per hour | Commercial use; additional fields, image processing, and usage analytics listed |
| Enterprise | $119/month | 100 requests per minute | Commercial use; additional fields, image processing, and usage analytics listed |
Taxes may apply. In addition to account quotas, per-domain throttling can limit throughput. Choose based on whether the project is personal or commercial, the request window you need, optional fields or image processing, and how much work you can queue and cache.
Production checklist
- Keep the API key server-side and rotate it through your secret-management process.
- Encode
qwith an HTTP client’s parameter facility. - Set connection and total timeouts; never let a remote page hold a web request open indefinitely.
- Check status before parsing JSON and sanitize every returned string.
- Accept blank fields and provide a usable text-only fallback.
- Proxy and cache images with byte, MIME, and timeout limits.
- Cache metadata in your application and explain that service refresh can take up to a day.
- Queue requests, enforce one-per-second-per-domain behavior where applicable, and back off on 429 and 503.
- Log status, target host, latency, and failure category without logging API keys or sensitive query data.
Or skip the browser setup
LinkPreview returns metadata for URL cards. If what you actually need is a rendered visual of a webpage for documentation, testing, or an image preview, ScreenshotNeo provides a screenshot API instead. One GET request can return PNG, JPEG, WebP, or a PDF, with options such as full-page capture, lazy-image loading, CSS-selector element capture, device presets, dark mode, custom CSS and JavaScript, waits, request blocking, cookies, headers, geolocation, resizing, caching, signed links, asynchronous jobs, webhooks, bulk capture, and an MCP server for AI agents.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for parameters and response headers. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account if a clean rendered capture is the output you need.
FAQ
Can I call LinkPreview directly from browser JavaScript?
You can technically send an HTTP request, but the documented security-oriented pattern is a server-side application so the API key remains private and your service can control access and rate limits.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Does a successful response guarantee a preview image?
No. The response can contain blank fields when the parser cannot extract metadata. Build a text-only card and treat image availability as optional.
Best Value
How quickly does changed page metadata appear?
Not necessarily immediately. LinkPreview caches pages, and its documentation says expiry can take up to a day.
What should I do when one host returns 426 repeatedly?
Throttle requests to that domain to no more than one per second, queue the work, and avoid parallel refreshes. The status means the per-domain request rate is too high.
Frequently Asked Questions
Can I call LinkPreview directly from browser JavaScript?
You can technically send an HTTP request, but the documented security-oriented pattern is a server-side application so the API key remains private and your service can control access and rate limits.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does a successful response guarantee a preview image?
No. The response can contain blank fields when the parser cannot extract metadata. Build a text-only card and treat image availability as optional.
How quickly does changed page metadata appear?
Not necessarily immediately. LinkPreview caches pages, and its documentation says expiry can take up to a day.
What should I do when one host returns 426 repeatedly?
Throttle requests to that domain to no more than one per second, queue the work, and avoid parallel refreshes. The status means the per-domain request rate is too high.
Quick Recap
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.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems
