Minifetch API

Fetch & extract metadata and data from web pages. Minifetch.com provides composable extraction APIs for humans and AI Agents-- making web pages simple to access.

• ✅ Sign up for an account and get your first fetches free. 🎉🎉
• ✅ Always pay-as-you-go at competitive prices.
• ⛔ No charge for blocked pages (403 errors).

👉 Dashboard | Full API docs | LLMs.txt | Questions? Join our Discord

Payments. Two ways to pay:

1. Credit card + API key. Get started free - visit our dashboard to Sign Up. Your account will be auto-loaded with 125–250 API calls. Top up with your credit card later.
2. x402. USDC stablecoin micropayments on Coinbase's Base & Solana networks.

Prerequisites

• Node.js v18+ & NPM
• A valid API key from our dashboard
• Or an Ethereum or Solana private key for making USDC payments on Base or Solana networks.

Install

npm install minifetch-api --save

Quick Start

import Minifetch from "minifetch-api";

// First, initialize the client with your payment choice:

// 1. API Key Payments:
const client = new Minifetch({
  apiKey: process.env.MINIFETCH_API_KEY
});

// 2. x402 Payments:
//   - Network options: "base" or "solana"
//   - Private key from wallet that has a small amt of USDC
const client = new Minifetch({
  network: "base",
  privateKey: process.env.BASE_PRIVATE_KEY,
});

// Now you're ready to extract data from a url:
try {
  const url = "example.com";
  const response = await client.checkAndExtractUrlPreview(url);
  // 200 "ok" responses
  console.log(response);
} catch (err) {
  // No charge for errors or 403 blocked urls!
  console.log(err);
}

Data Extraction Methods

After the Quick Start, you have the following methods to use. The "checkAndExtract" methods help to avoid paying for blocked URLs. Price list & example data is here.

Wrap these in a try/catch just like in the Quickstart example above. Code examples can be also found in the Github repository /example- directories.

// Extracts a light, token-efficient preview of a URL:
// title, description, and image (only).
await client.checkAndExtractUrlPreview(url);

// Extracts a clean, token-efficient content summary as markdown from a URL.
// Removes ads, nav, scripts. More efficient than raw HTML fetches for LLMs.
// Options: { includeMediaUrls: true } - defaults to false.
await client.checkAndExtractUrlContent(url, options);

// Extracts all links from a URL categorized by type (internal/external/anchor).
// Detects image links, nofollow attributes, analyzes external domain distribution.
await client.checkAndExtractUrlLinks(url);

// Extracts rich structured metadata from a URL:
// meta tags, json-ld, images, headings, response headers, + more.
// Setting verbosity to "full" is the drop-in replacement for the
// `url-metadata` package.
// Options:
// { verbosity: "full" } - defaults to "standard"
// { includeResponseBody: true } - defaults to false
await client.checkAndExtractUrlMetadata(url, options);

// For max control, you can also use the following methods directly.
// Free - check robots.txt:
await client.preflightCheck(url);
// Extract data:
await client.extractUrlPreview(url);
await client.extractUrlContent(url, options); // same options as above
await client.extractUrlLinks(url);
await client.extractUrlMetadata(url, options) // same options as above

Error Types

When you wrap the functions above in a try/catch, here are the errors you may encounter. You are never charged for errors.

• "RobotsBlockedError: URL is blocked by robots.txt"
  • URL is explicitly blocked by the website's robots.txt, cannot be fetched.
• "Network Error: 402 Payment Required"
  • Check your wallet -- likely you ran out of USDC to pay!
• "Network Error: 429 Too Many Requests"
  • Back off and retry, max 5-10 requests per second.
• "Network Error: 502 Bad Gateway"
  • URLs that pass their robots.txt check but are blocked anyway via 403 or other tactics may error like this.
• "503 Service Temporarily Unavailable"
  • Likely encountering upstream timeout errors on the target URL.
• "InvalidURLError: Invalid url ${url}"
  • The URL is malformed in some way, correct it and try again.

Service Limitations

Minifetch only extracts publicly available metadata and content from pages accessible without authentication and javascript execution.

What Minifetch does NOT do:

• Ignore robots.txt directives
• Access authenticated or logged-in content
• Create accounts or log into user sessions
• Perform transactional actions (checkout, bidding, purchasing, form submissions)
• Bypass paywalls or access restricted content

What Minifetch does NOT do currently but may offer in the future as an add-on:

• Javascript execution

x402 Best Practices

• LLMs & Agents should never have direct access to your private key. They will expose it!
• Only keep a small amount of USDC in the account whose private key you use.
• Keep that account separate from the rest of your onchain funds.
• Pass your private key into the Minifetch API Client via an environment variable.

License

MIT / Copyright (c) 2026 Lauren Garcia This package is an API client for Minifetch.com. The client code is open source, but use of the Minifetch API is subject to the Minifetch.com Terms of Service.