Fetch only the metadata fields you need
A metadata API should let you select fields, because the default payload detects every field, resolves every image and checks every URL. A search indexer that only needs the title, or a text pipeline that never shows a logo, waits for all of it. The meta object turns detection into a menu, and filter trims the JSON to the keys you read.
Full metadata detection is the expensive default
Detecting an image means finding candidates, fetching them, measuring them and verifying they load. Detecting a logo does the same for favicons and touch icons. When the consumer never renders either, that is wasted time on every uncached request.
Dropping the fields client-side changes nothing: the work already happened and the bytes already crossed the network. Writing a separate lightweight scraper for the title-only jobs means a second codebase, one that loses the normalization across Open Graph, Twitter Cards, JSON-LD and the HTML.
Pass meta as an object. Fields set to true are the only ones detected; fields set to false are removed from the default set. Combine it with filter for the response shape and each request carries exactly what the consumer reads. The choosing fields guide has the include versus exclude table.
How to select fields for fast metadata extraction
There are two ways to scope detection, include and exclude, and one way to scope the response. All three work on the free endpoint.
import createClient from 'microlink.io'
const microlink = createClient({
apiKey: process.env.MICROLINK_API_KEY
})
const { title, description } = await microlink.metadata('https://example.com', {
meta: { title: true, description: true }
})Only title and description are detected. image, logo and the rest of the default set are never processed.
import createClient from 'microlink.io'
const microlink = createClient({
apiKey: process.env.MICROLINK_API_KEY
})
const { title, author, date } = await microlink.metadata('https://example.com', {
meta: { image: false, logo: false }
})The default set minus media: title, description, lang, author, publisher, date and url, without any image fetching.
curl 'https://api.microlink.io/?url=https%3A%2F%2Fexample.com&meta.title=true&meta.description=true&filter=title%2Cdescription'meta scopes detection and filter trims the JSON to the listed keys. filter accepts dot notation, so image.url returns one property of a media field.
- meta Object of field names set to true (include only) or false (exclude). Default true, which detects everything.
- filter Comma-separated list of keys to keep in the JSON response, with dot notation for nested fields.
- ping Default true. Pass false, or an object such as { audio: false }, to skip reachability checks.
- prerender false forces a plain HTTP GET for pages you know are server-rendered. Default auto.
- javascript Default true. Set false when the page does not need JavaScript to expose its metadata.
meta: false disables detection entirely, and the x-fetch-mode header reports skipped. That is the right setting when the request only exists for a screenshot, a PDF or custom rules. The caching and performance guide ranks the other speedups.
Why scoping fields makes for a lightweight link preview API
Every skipped field is work the API does not do and bytes the network does not carry.
For link previews at scale the saving multiplies across every uncached request.
The delivery and response guide covers filter next to the other ways of shaping the output.
When not to: while exploring a new source, request the default set first to see what the page exposes, and narrow the request once you know which fields are reliable. The same trim-the-work idea applies to faster, smaller screenshots.
FAQ
How do I request only some metadata fields?
How do I skip image and logo detection in a metadata request?
What is the difference between meta and filter in the metadata API?
Does selecting metadata fields change the cache entry?
Which metadata fields are returned by default?
Solve the next problem with the same API
Link previews at scale
Custom fields alongside metadata
Brand colors from images
Metadata from single-page apps
Faster, smaller screenshots
Clean Markdown, no boilerplate
Ready for lean metadata requests?
Detect only what you render and return only what you read. Start on the free tier and trim your first request today.