The metadata endpoint turns one public URL into a normalized JSON object for previews, search indexes, moderation workflows, or your own UI.

GET https://api.linkmetadata.com/v1/metadata?url=https://example.com

Query parameters

Parameter	Required	Values	Description
url	Yes	Absolute URL	Page to fetch and inspect. HTTP and HTTPS pages are the supported use case.
prefer	No	og, twitter	Preferred source for the normalized fields. Defaults to og.
allow_fallback	No	true, false	Reserved for fallback control. Current responses use normal fallback behavior.

prefer affects title, description, url, image, and type. It does not remove raw og or twitter data from the response.

GET https://api.linkmetadata.com/v1/metadata?url=https://example.com&prefer=twitter

Fetch from JavaScript

Use the Fetch API from browsers, workers, or server runtimes:

const params = new URLSearchParams({
  url: "https://example.com",
  prefer: "og"
});

const response = await fetch(`https://api.linkmetadata.com/v1/metadata?${params}`);

if (response.status === 429) {
  throw new Error("Rate limit reached. Wait 10 seconds before retrying.");
}

if (!response.ok) {
  throw new Error(`Metadata request failed with ${response.status}`);
}

const metadata = await response.json();

Access and rate limits

The API is free to use. It does not require authentication, signup, or API keys.

Requests are rate limited per IP address:

Limit	Block window
20 requests per 10 seconds	10 seconds

When an IP reaches the limit, further requests from that IP are blocked for 10 seconds. Client apps should avoid tight retry loops and wait before trying again.

Successful response

A successful request returns 200 OK with application/json.

Field	Type	Description
title	string | null	Best title found for the page.
description	string | null	Best page description.
url	string	Canonical or representative URL.
image	ImageMetadata	Primary preview image metadata.
favicon	ImageMetadata	Favicon metadata.
type	string | null	Open Graph type or Twitter card type.
og	Record<string, string>	Raw Open Graph tags found on the page.
twitter	Record<string, string>	Raw Twitter Card tags found on the page.
safety_tags	string[]	Readable safety labels. Empty when no tag applies or lookup fails.

Field selection

For normalized fields, LinkMetadata reads the preferred metadata family first, then falls back to other page data.

Field	Main sources
title	og:title or twitter:title, then the HTML <title>.
description	og:description or twitter:description, then <meta name="description">.
url	og:url or twitter:url, then <link rel="canonical">, then the requested URL.
image	og:image, og:image:secure_url, og:image:url, twitter:image, or twitter:image:src.
type	og:type or twitter:card.
favicon	Best icon link on the page, then /favicon.ico.

If the target response is not HTML, the API still returns a normalized object with unavailable fields set to null where possible.

For the full priority order, see Metadata extraction rules.

Image metadata

Field	Type	Description
url	string | null	Absolute image URL, or null when none is available.
type	string | null	Image MIME type when known.
width	number | null	Width in pixels when known.
height	number | null	Height in pixels when known.
size	number | null	Image size in bytes when known.
cors_safe	boolean | undefined	Whether the image response includes permissive browser CORS headers.

Image analysis is best effort. A page can still have a useful image.url even when width, height, MIME type, or size is unavailable.

For proxy behavior and browser CORS guidance, see Images and CORS.

Safety tags

Possible safety_tags values:

Tag	Meaning
adult	Known adult content.
security_threat	Known malware, phishing, or other threat domain.
suspicious_domain	Parked domain, new high-entropy domain, or IP URL.

Treat safety tags as signals for product decisions, not as a complete security verdict.

For recommended handling patterns, see Safety tags.

Redirects and errors

Requests without url redirect to the same endpoint with a showcase URL. API clients should pass url explicitly instead of relying on this behavior.

HTTP/1.1 302 Found
Location: https://api.linkmetadata.com/v1/metadata?url=https%3A%2F%2Fauthpi.com

Application errors use a JSON object with code and message.

Status	When it happens
400	The request is malformed or validation fails.
429	The per-IP rate limit was reached. Wait before retrying.
422	The URL is valid, but the page could not be fetched or parsed.
500	An unexpected server error occurred.

{
  "code": 422,
  "message": "Failed to fetch https://example.com: fetch failed"
}

Caching

Successful metadata responses are cacheable for 12 hours.

Cache-Control: public, max-age=43200

The cache key includes the full request URL, so different query strings can produce separate cached entries.

For generated OpenAPI details, see API Reference.