Skip to main content
When a user pastes a video link into your app, you usually want a preview before anything else: the title, a thumbnail and how long it is. Scraping that yourself means a different parser per site, and from a server many sites answer with a bot check instead of the page. This route sends the link to Importly’s basic metadata endpoint and returns a small preview object. It runs on Node 18 or later with Express.

The code

preview.mjs
Create your key on the API key page (it’s shown once) and keep it on the server. The browser only calls your /api/preview route.

What comes back

The finished job from GET /metadata/basic/status has four fields under result:
duration is in seconds. A live stream that hasn’t ended has isLive: true and duration: null, so show a “Live” badge instead of a length. It can’t be downloaded or transcribed until the stream ends. For the description, uploader, upload date or view counts, call POST /metadata instead. It costs the same and returns everything the source exposes.

Errors to handle

Every error has a documentationUrl with the fix. See Error handling.

In production

  • Swap the Map for your database or Redis, keyed by the link, so a preview is looked up once across restarts and servers.
  • If you store the thumbnail, copy the image to your own storage. Some platforms sign their image links, and those stop working after a while.
  • Use duration to check a video before a bigger job: reject anything over your length limit before you pay to download or transcribe it.
  • Saving previews in the background (a feed, an import queue)? Pass a webhookUrl and save the result when Importly calls you back. See Webhooks.
A preview costs $0.003 per link, and status checks are free. Try it free, no card required. See Pricing & credits.