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).
1. Store each link as a row
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
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
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 onePOST 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
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
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
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.