On this page7 sections
When a user pastes a video link into your app, the first thing you usually need isn't the file. It's the title for the preview card, the duration to check against a limit, and a thumbnail to show while anything else runs. Getting that for one site is easy. Getting it for whatever link a user pastes, from a server, is where it gets messy.
What the platforms give you
Start with the official routes, because for some apps they're enough:
- YouTube Data API.
videos.listreturns the title, description, channel, view count and duration (as an ISO 8601 string likePT4M13S). It needs a Google API key, and calls count against a daily quota. It only covers YouTube. - oEmbed. YouTube, Vimeo, TikTok and others expose an oEmbed endpoint that returns the title, author and a thumbnail without a key. It's built for embedding, so it doesn't include the duration, and each site has its own endpoint and fields.
- Scraping the page. Reading
og:titleandog:imagefrom the HTML works until a site serves a consent wall, a login prompt or a bot check to your server instead of the page.
If you only take YouTube links, the Data API is a fine answer. Most apps don't get to choose what users paste: it's YouTube today, then a TikTok, a Loom, an X post or a podcast episode. That means one integration per site, each with its own auth, fields and failure modes, and a server that gets blocked on the ones that don't like datacenter traffic.
One call for any supported link
Importly has two metadata endpoints. Both take any supported link, cost $0.003 per call and never download the media.
| Endpoint | Returns | Good for |
|---|---|---|
POST /metadata/basic | title, duration, thumbnail, isLive | Link previews, validating a link, length checks. Faster |
POST /metadata | Everything the source exposes: description, uploader, upload date, view and like counts, tags, every thumbnail and format | Cataloguing, analytics, picking a quality |
curl -X POST https://api.importly.io/metadata/basic \
-H "Authorization: Bearer $IMPORTLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"}'A playlist page is rejected up front. Metadata runs as a job, like every endpoint. Poll GET /metadata/basic/status?id=<jobId> or pass a webhookUrl, and the result looks like this:
{
"title": "Me at the zoo",
"duration": 19,
"thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
"isLive": false
}duration is in seconds, the same shape for every site. Some platforms don't expose a length for some posts; then duration is null, and your code should treat it as unknown rather than zero.
Check the length before you pay to download
The most common use is a guard in front of an import. A user pastes a link; you read the duration first and only fetch the file if it fits your rules:
const meta = await getBasicMetadata(url) // POST /metadata/basic, then poll or webhook
if (meta.isLive) {
return reject("Live streams can't be imported. Paste the recording once it ends.")
}
if (meta.duration && meta.duration > 30 * 60) {
return reject("Videos over 30 minutes aren't supported on your plan.")
}
await startImport(url) // POST /importAt $0.003 a check, this costs far less than downloading a two-hour video you were going to throw away. It also catches private, deleted and login-only links up front, so your user sees a clear error in the form instead of a failed job later.
The same check works for transcripts: read the duration, estimate speech-to-text at $0.01 per minute, and show the user the cost or set maxCostDollars on the request.
Full metadata
POST /metadata returns the source's own fields in snake_case, so what you get depends on the platform. The ones most apps use:
title,description,tagsuploader,uploader_id,upload_date(YYYYMMDD)view_count,like_count, when the platform shows themthumbnails(every size offered) andformats(every stream with height, fps, codecs and file size)
Use formats to decide which quality to request in an import. Don't fetch the stream URLs in it directly: they expire quickly and are often tied to the IP that read them, so they tend to fail from your server. Ask for the file with POST /import instead. The field list is in the metadata docs.
From a server or an agent
These calls behave the same from a Lambda function, a container on Fly or Render, or a CI job as they do on your laptop. That's the case where self-hosted scrapers and per-site libraries tend to break: datacenter IPs get the bot check, and the preview that worked locally comes back empty in production.
If you're building with a coding agent, connect https://mcp.importly.io/mcp to Claude Code, Cursor or another agent and ask it to add link previews or a length check to your app. It gets working code for your stack, tests real calls with your API key, and your backend uses the same key. See Have your agent build Importly into your app.
What it costs
$0.003 per metadata call, basic or full. Status checks are free. It's free to try, no card required. See pricing.
FAQ
How do I get a YouTube video's duration from a URL?
With the YouTube Data API, call videos.list with part=contentDetails and parse the ISO 8601 duration. With Importly, POST /metadata/basic returns duration in seconds for YouTube and every other supported site.
Does oEmbed return the video duration?
Usually not. oEmbed is meant for embedding a player, so most providers return the title, author and thumbnail only.
Can I get metadata without downloading the video?
Yes. Both metadata endpoints read the details from the link and never download the media.
Does it work for private videos?
No. Links that need a login or are restricted to specific people fail, so you can ask the user for a public link.
Related: Import video from URL API, How to build an import from URL feature, Video downloader API.