What is Share Preview API?

The Share Preview API is a powerful service that extracts Open Graph (OG) metadata from any URL on the internet. When you share a link on social media platforms like Twitter, Facebook, or LinkedIn, these platforms use OG metadata to display a rich preview card with the page's title, description, and image.

Our API makes it easy to programmatically fetch this data without having to parse HTML or deal with CORS issues. It's perfect for:

• Link preview tools — Show users what their links will look like before posting
• Social media schedulers — Auto-fetch preview data for bulk content
• URL shorteners — Display rich previews for shortened links
• SEO tools — Audit OG metadata across competitors
• Content discovery — Build recommendation engines with metadata
• QA/testing — Validate that your website's OG tags are correct

Unlike alternatives like Embedly or MetaAPI, Share Preview prioritizes speed, reliability, and developer experience. Our average response time is 200ms, and we handle 500K+ requests daily without degradation.

Getting Started with Share Preview API

Step 1: Create an Account

Visit our homepage and sign up for a free account. You'll get:

• 100 free requests per day
• Your unique API key
• Access to all core endpoints

Step 2: Get Your API Key

After signing up, go to your dashboard to find your API key. Keep it private—treat it like a password. You'll use it to authenticate all requests:

Authorization: Bearer YOUR_API_KEY_HERE

Step 3: Make Your First Request

Here's the simplest possible API call:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.share-preview.com/v1/preview?url=https://example.com"

Response (200 OK):

{
  "success": true,
  "url": "https://example.com",
  "title": "Example Domain",
  "description": "Example Domain. This domain is established...",
  "image": "https://example.com/image.png",
  "favicon": "https://example.com/favicon.ico",
  "site_name": "Example",
  "twitter_card": "summary_large_image"
}

Core Endpoints Reference

POST /v1/preview

Fetch OG metadata for a single URL.

POST /v1/preview/batch

Fetch metadata for multiple URLs (up to 50 per request).

{
  "urls": [
    "https://example1.com",
    "https://example2.com",
    "https://example3.com"
  ],
  "cache": true
}

GET /v1/status

Check API health and your current rate limit status.

{
  "status": "operational",
  "requests_today": 42,
  "requests_remaining": 58,
  "reset_time": "2026-02-27T00:00:00Z"
}

GET /v1/cache/{url_hash}

Check if a URL is cached and when it was last updated.

{
  "cached": true,
  "last_updated": "2026-02-20T14:30:00Z",
  "expires_at": "2026-03-09T14:30:00Z"
}

Code Examples

JavaScript / Node.js

// Fetch preview for single URL
const response = await fetch('https://api.share-preview.com/v1/preview', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHARE_PREVIEW_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com' })
});

const preview = await response.json();
console.log(preview.title);     // Output: "Example Domain"
console.log(preview.image);     // Output: image URL
console.log(preview.description); // Output: page description

Python

import requests
import os

API_KEY = os.getenv('SHARE_PREVIEW_API_KEY')
headers = {'Authorization': f'Bearer {API_KEY}'}

# Batch request for multiple URLs
response = requests.post(
    'https://api.share-preview.com/v1/preview/batch',
    headers=headers,
    json={
        'urls': ['https://example1.com', 'https://example2.com'],
        'cache': True
    }
)

previews = response.json()['data']
for preview in previews:
    print(f"{preview['title']} - {preview['url']}")

React Component

import { useState, useEffect } from 'react';

export function LinkPreview({ url }) {
  const [preview, setPreview] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('/api/preview', {
      method: 'POST',
      body: JSON.stringify({ url })
    })
    .then(r => r.json())
    .then(data => {
      setPreview(data);
      setLoading(false);
    });
  }, [url]);

  if (loading) return <div>Loading...</div>;
  if (!preview) return null;

  return (
    <div className="preview-card">
      <img src={preview.image} alt={preview.title} />
      <h3>{preview.title}</h3>
      <p>{preview.description}</p>
    </div>
  );
}

Rate Limits & Optimization

Rate Limit Tiers

Handling Rate Limits

When you exceed rate limits, the API returns a 429 (Too Many Requests) response:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1645939200

Always check the Retry-After header and back off exponentially:

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch('/api/preview', {
      body: JSON.stringify({ url })
    });

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After'));
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response.json();
  }
}

Optimization Tips

• Use batch requests — Fetch up to 50 URLs per request instead of 50 individual calls
• Enable caching — Set cache: true to get instant responses for recent URLs
• Implement local caching — Store results for 7-30 days depending on your use case
• Queue requests during off-peak hours — Distribute API calls throughout the day

Webhooks Integration

Webhooks let you receive real-time notifications when URLs are updated. This is useful for:

• Keeping your cache fresh automatically
• Notifying users when shared links have new preview data
• Monitoring competitors' website changes
• Triggering downstream processes when OG data changes

Setting Up a Webhook

Go to your dashboard, click "Webhooks", and create a new endpoint:

POST /webhooks/share-preview

Example payload:
{
  "event": "url.updated",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "url": "https://example.com",
    "title": "New Title",
    "image": "https://example.com/new-image.png",
    "previous_title": "Old Title"
  }
}

Webhook Security

All webhooks are signed with HMAC-SHA256. Verify the signature:

import crypto from 'crypto';

const signature = req.headers['x-webhook-signature'];
const body = req.rawBody; // Raw body, not parsed JSON
const secret = process.env.WEBHOOK_SECRET;

const hash = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

if (hash !== signature) {
  throw new Error('Invalid webhook signature');
}

Caching Strategies

API-Side Caching (Built-in)

Share Preview automatically caches results for 30 days. Subsequent requests for the same URL are served from cache (typically within 50ms).

To bypass cache or force a fresh fetch:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.share-preview.com/v1/preview?url=https://example.com&cache=false"

Application-Level Caching

Cache API responses in your own database or Redis for 7-30 days:

// Redis example
const cacheKey = `preview:${url}`;
let preview = await redis.get(cacheKey);

if (!preview) {
  preview = await sharePreviewAPI.fetch(url);
  await redis.setex(cacheKey, 7 * 24 * 60 * 60, JSON.stringify(preview));
}

return preview;

When to Refresh Cache

• Fresh content sites (news) — 1-3 days
• E-commerce — 7 days
• Static/documentation — 30+ days
• User-generated content — 12 hours
• Use webhooks — Immediate updates when URLs change

Frequently Asked Questions

What is the difference between Share Preview API and alternatives?

Share Preview is built for developers, by developers. We prioritize:

• Speed — 200ms average response time vs 500ms+ for competitors
• Reliability — 99.99% uptime SLA, no surprise downtimes
• Transparency — Clear pricing, no hidden fees or seat-based billing
• Support — Real humans, not chatbots. Response time < 2 hours
• Developer Experience — Best-in-class documentation and error messages

Does Share Preview handle redirects?

Yes. The API follows up to 5 HTTP redirects automatically. If a URL redirects to another domain, we'll return the final destination's metadata.

What about private/paywalled content?

The API can fetch OG tags from private pages if they're publicly accessible (e.g., behind login). Some sites block automated access—in those cases, the API returns available metadata or an error.

Can I cache results forever?

We recommend refreshing cache every 7-30 days to catch updates. Use our webhook system to get instant notifications when URLs change—this lets you refresh only what's actually updated.

Do you have a status page?

Yes, check our status page for real-time uptime and incident history.

Next Steps

• 📖 Read the full API documentation
• 🛠️ Check out integration guides for your tech stack
• 💬 Join our community Discord
• 📧 Email support: [email protected]