Skip to main content
This recipe is for apps that take many links at once: a user uploads a CSV, pastes a list of episodes, or connects a feed, and your backend imports every one. The hard parts aren’t the API call. They’re not spending more than you meant to, not tripping rate limits, and not losing track of a job when a webhook never arrives. The code is plain TypeScript with fetch. It assumes an imports table in your own database and a job that runs every minute (a cron route, a queue worker or a setInterval in a long-running server). Keep IMPORTLY_API_KEY on the server: create it on the API key page (it’s shown once). Write one row per link when the user submits the batch, and import from those rows rather than from the request. Then a restart, a deploy or a full balance never loses a link:
lib/imports.ts
Import one link per video. A youtube.com/playlist?list=… page is rejected with PLAYLIST_NOT_SUPPORTED before a job is created, so expand playlists into their video links before you store them. A watch URL with &list= in it is fine; it’s treated as that one video.

2. Send at a steady pace

POST /import allows 240 requests per hour per key, so this sender starts at most 4 imports a minute, which fits under the limit with room for retries. Each import gets a maxCostDollars cap, because links in a batch come from users and one of them may be a three-hour 4K stream:
lib/send-imports.ts
The 402 throws so your job runner stops and alerts you: every other link in the batch would get the same answer. Check the balance with GET /balance before a large batch if you’d rather warn the user up front. A 10-minute 720p video is about $0.15, so a batch of 200 of them is about $30.

3. Settle each job from the API

Importly sends one POST to webhookUrl when a job completes or fails. The handler takes only the jobId from it and reads the job with your key, so a forged request can’t put data into your app. Every delivery is also signed: to reject forged requests before calling the API, check the Importly-Signature header as shown in Verify signatures. The same settleJob function is used again by the sweep in step 4:
lib/settle-job.ts
The webhook route only parses the body and hands the jobId over. It’s a Next.js route handler here; in Express or Hono the body is the same:
app/api/webhooks/importly/route.ts
The webhook URL must be public https://. In local development there’s no webhook, and the sweep below settles every job on its own.

4. Sweep for missed webhooks

Each job gets one webhook delivery and no retries, so a deploy or an outage on your side can miss one. Run the sweep from the same once-a-minute job as the sender:
lib/sweep-imports.ts
A job that’s still queued or running stays submitted and is checked again on the next run. Status checks allow 3,600 requests per hour, so 50 a minute leaves plenty of room. Long videos can take a few minutes to download; the sweep just keeps looking until they finish.

What each failure means for a batch

Failed imports aren’t charged, except MAX_COST_EXCEEDED (the price check) and FILE_TOO_LARGE, where the file outgrew your balance partway and you pay for what was downloaded. All the codes are on Errors & rate limits.
Downloads cost $0.002 per MB, with a $0.01 minimum per import. Add includeTranscript: true to get the transcript in the same job, or store: true to have every file land in your own bucket. Try it free, no card required. See Pricing & credits.

Let your agent write it

Using Claude Code or Cursor on this app? Connect the MCP server and ask it to add batch imports with Importly. It reads the same docs, fits the queue to your database and job runner, and can test with a few real links first. See Build with your agent.