Site (Unfurl) API

Extract OpenGraph metadata, Twitter Cards, and HTML meta tags from any URL to create rich link previews.

Endpoint

HTTP

GET https://opengraph.io/api/1.1/site/{encoded_url}?app_id=YOUR_APP_ID

Parameters

Path Parameters

Parameter	Type	Description
encoded_url	string	Required. URL-encoded target URL

Query Parameters

Parameter	Type	Default	Description
app_id	string	-	Required. Your API key
cache_ok	boolean	true	Allow cached results
full_render	boolean	false	Enable JavaScript rendering for SPAs
use_proxy	boolean	false	Use standard proxy
use_premium	boolean	false	Use residential proxy
use_superior	boolean	false	Use mobile proxy (highest success rate)
use_ai	boolean	false	Enable AI enhancement for better metadata extraction
max_cache_age	number	432000	Maximum cache age in seconds (default: 5 days)
accept_lang	string	en-US	Language header
auto_proxy	boolean	false	Automatically select optimal proxy (eligible plans only)
proxy_country	string	-	Specify proxy country code (e.g., US, GB, DE)

Retry Options

The retry feature automatically re-attempts failed requests using progressively stronger proxy levels to maximize success rates on difficult-to-scrape websites. Instead of a single failed request, the API will make multiple attempts, escalating through proxy tiers until it succeeds or exhausts all options.

Parameter	Type	Default	Description
retry	boolean	false	Enable automatic retry with proxy escalation on failure
max_retries	number	4	Maximum retry attempts (1-4)
retry_escalate	boolean	true	Escalate proxy level on each retry

How Retry Works

When retry=true is enabled:

Initial Request — The API attempts the request at your specified proxy level (or no proxy)
On Failure — If the request fails with a retryable error (timeout, 403, 429, 500-504), it automatically retries
Proxy Escalation — Each retry escalates to a stronger proxy tier:
- Attempt 1: No proxy (or your starting level)
- Attempt 2: Standard proxy (use_proxy)
- Attempt 3: Residential proxy (use_premium)
- Attempt 4: Mobile proxy (use_superior)
Success — Returns the result from whichever attempt succeeded
Billing — You're only charged for the proxy level that succeeded

Response Metadata

When retry is used, the response includes retryInfo:

Retry Response

{
  "hybridGraph": { ... },
  "retryInfo": {
    "attempts": 2,
    "successfulProxyLevel": "use_premium",
    "creditCost": 3,
    "attemptDetails": [
      { "attempt": 1, "proxyLevel": null, "success": false, "error": "403" },
      { "attempt": 2, "proxyLevel": "use_premium", "success": true }
    ]
  }
}

Requirements: Retry requires access to the superior proxy tier (retry can escalate to any level). You're charged based on the successful proxy level, not failed attempts.

Example Request

curl "https://opengraph.io/api/1.1/site/https%3A%2F%2Fgithub.com?app_id=YOUR_APP_ID"

Example Response

Response

{
  "hybridGraph": {
    "title": "GitHub: Let's build from here",
    "description": "GitHub is where over 100 million developers shape the future of software.",
    "image": "https://github.githubassets.com/images/modules/site/social-cards/github-social.png",
    "url": "https://github.com/",
    "site_name": "GitHub",
    "type": "website",
    "favicon": "https://github.githubassets.com/favicons/favicon.svg"
  },
  "openGraph": {
    "title": "GitHub: Let's build from here",
    "description": "GitHub is where over 100 million developers...",
    "type": "website",
    "url": "https://github.com/",
    "site_name": "GitHub",
    "image": {
      "url": "https://github.githubassets.com/images/modules/site/social-cards/github-social.png"
    }
  },
  "htmlInferred": {
    "title": "GitHub: Let's build from here",
    "description": "GitHub is where over 100 million developers...",
    "favicon": "https://github.githubassets.com/favicons/favicon.svg"
  },
  "requestInfo": {
    "redirects": 0,
    "host": "github.com",
    "responseCode": 200
  }
}

Response Fields

Field	Description
hybridGraph	Merged data from OpenGraph, Twitter Cards, and HTML inference. Use this for best results.
openGraph	Raw OpenGraph tags found on the page
twitterCard	Twitter Card metadata if present
htmlInferred	Values inferred from HTML (title tag, meta description, etc.)
requestInfo	Information about the request (redirects, response code)

Tip: Use hybridGraph for the most complete data. It intelligently merges data from all sources with smart fallbacks.

Use Cases

Generate link previews for messaging apps and social platforms
Content curation and aggregation tools
SEO analysis and monitoring
Social media management platforms

MCP Tool

This endpoint is available as the Get OG Data tool in the OpenGraph MCP Server. Your AI assistant can fetch metadata directly without writing any code.

Get started with MCP in 2 minutes →

Learn more about MCP integration →