← Back to Quick Start

Extract Metadata from Any URL

Fetch any URL and extract its title, description, Open Graph tags, Twitter Cards, and more — with built-in SSRF protection.

What you'll learn

  • How to extract page title, description, and Open Graph metadata from any URL
  • How the API handles redirects and follows them safely
  • How to use extracted metadata for link previews and social sharing
  • How SSRF protection keeps your infrastructure safe

Prerequisites

Step 1: Your first call

Fetch metadata from example.com:

curl -s -X POST /api/v1/url-metadata/fetch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com"
  }' | python3 -m json.tool

Expected response:

{
  "url": "https://example.com",
  "finalUrl": "https://example.com",
  "statusCode": 200,
  "title": "Example Domain",
  "description": "This domain is for use in illustrative examples in documents.",
  "language": "en",
  "contentType": "text/html; charset=UTF-8",
  "openGraph": {},
  "twitterCard": {},
  "favicon": null,
  "redirectChain": [],
  "processingTimeMs": 320
}

Step 2: Understanding the response

finalUrl The URL after following all redirects. Compare with url to detect redirections.
title The page's <title> tag content.
description From <meta name="description"> or inferred from page content.
openGraph All og: meta tags as key-value pairs (og:title, og:image, og:type, etc.).
twitterCard All twitter: meta tags (twitter:card, twitter:site, etc.).
redirectChain Array of intermediate URLs if the original URL was redirected.

Step 3: Common use cases

Rich Open Graph metadata

curl -s -X POST /api/v1/url-metadata/fetch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url": "https://github.com/about"}'
{
  "url": "https://github.com/about",
  "finalUrl": "https://github.com/about",
  "statusCode": 200,
  "title": "About GitHub",
  "description": "GitHub is where over 100 million developers shape the future of software.",
  "openGraph": {
    "og:title": "About GitHub",
    "og:description": "GitHub is where over 100 million developers shape the future of software.",
    "og:image": "https://github.githubassets.com/images/modules/open_graph/github-logo.png",
    "og:type": "website",
    "og:url": "https://github.com/about"
  },
  "twitterCard": {
    "twitter:card": "summary_large_image",
    "twitter:site": "@github"
  },
  "favicon": "https://github.githubassets.com/favicons/favicon.svg",
  "processingTimeMs": 450
}

Following redirects

curl -s -X POST /api/v1/url-metadata/fetch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url": "http://github.com"}'
{
  "url": "http://github.com",
  "finalUrl": "https://github.com/",
  "statusCode": 200,
  "redirectChain": [
    "http://github.com -> https://github.com/ (301)"
  ],
  "title": "GitHub: Let's build from here",
  ...
}

Handling a 404 page

curl -s -X POST /api/v1/url-metadata/fetch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url": "https://example.com/nonexistent-page"}'
{
  "url": "https://example.com/nonexistent-page",
  "finalUrl": "https://example.com/nonexistent-page",
  "statusCode": 404,
  "title": "404 Not Found",
  "description": null,
  ...
}

Step 4: Handling errors

SSRF-blocked URL (private IP)

curl -s -X POST /api/v1/url-metadata/fetch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url": "http://169.254.169.254/latest/meta-data/"}'
{
  "error": "SSRF_BLOCKED",
  "message": "URL resolves to a private/internal IP address and is blocked for security",
  "status": 403
}

Invalid URL

{
  "error": "VALIDATION_ERROR",
  "message": "url: must be a valid HTTP or HTTPS URL",
  "status": 400
}

Step 5: Integration tips

Python link preview generator

import requests

API_BASE = ""
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

def get_link_preview(url):
    resp = requests.post(
        f"{API_BASE}/api/v1/url-metadata/fetch",
        json={"url": url},
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    data = resp.json()

    og = data.get("openGraph", {})
    return {
        "title": og.get("og:title") or data.get("title"),
        "description": og.get("og:description") or data.get("description"),
        "image": og.get("og:image"),
        "favicon": data.get("favicon"),
        "url": data.get("finalUrl")
    }

preview = get_link_preview("https://github.com/about")
print(f"Title: {preview['title']}")
print(f"Image: {preview['image']}")

Use cases for URL metadata

Next steps