On this page5 sections
If your app lets users paste an X post and you need the video file, here's where it usually goes wrong:
- The quick hacks stop working. Unofficial endpoints and page scraping that found the video URL last month return errors this month, often all at once.
- It breaks on the server. Requests that work from your laptop get blocked or rate-limited once they come from AWS, GCP, Fly, a Vercel function or an agent sandbox.
- You get streams, not a file. X serves video in several bitrates and formats. Whatever route you use, you still have to pick the right one and turn it into a single MP4.
- Links come in two domains. Users paste
x.comandtwitter.comlinks, with and without tracking parameters, and both need to work.
The free route, if you have API access
If you already have an X developer account with read access, the official API v2 can give you the video. Look up the post with expansions=attachments.media_keys and media.fields=variants, and each video comes back with a list of variants: MP4 files at different bitrates plus a streaming playlist. Take the MP4 with the highest bit_rate and download it.
That works and stays within X's terms. What it costs you is the developer account and its read limits, token handling, and code to pick the variant and deal with posts that have no video, several videos or a quoted post. And if you don't have API access, there's no stable free route from a server.
One call with Importly
Importly takes the post link your user pasted and gives you the video file, from servers and agent sandboxes, with no X developer account.
curl https://api.importly.io/import \
-H "Authorization: Bearer $IMPORTLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://x.com/<user>/status/<id>",
"webhookUrl": "https://your.app/webhooks/import"
}'When the job finishes, the webhook (or GET /import/status?id=<jobId>) gives you a signed link to the MP4 plus its title, duration and thumbnail. The link lasts 7 days; set "store": true to have the file copied straight into your own S3, R2 or B2 bucket instead.
A few things worth knowing:
- Pick the quality you need.
videoQualityis a ceiling (720pby default), and Importly takes the best stream at or below it, so you don't have to compare bitrates yourself. - Audio only: set
"includeVideo": falseto get just the soundtrack. - Transcript: add
"includeTranscript": trueto get a timestamped transcript in the same job. If the video has no captions, add"transcriptProvider": "importly"for AI speech-to-text at $0.01 a minute. - Check before you pay:
POST /metadata/basicreturns the title and duration for $0.003, so you can confirm a post has a video and how long it is before downloading. - Deleted, private or login-only posts fail fast with a clear
code(VIDEO_UNAVAILABLE,VIDEO_PRIVATE,AUTH_REQUIRED), so you can tell the user instead of retrying. Failed imports aren't charged.
What it costs
Downloads are $0.002 per MB, with a $0.01 minimum per import. A one-minute clip at 720p is typically 10 to 20 MB, so about two to four cents. Set maxCostDollars on a request and Importly checks the price before downloading anything. New accounts get $3 of free credit, no card. See pricing for the full list.
Have your AI agent build it in
Connect https://mcp.importly.io/mcp to Claude Code, Cursor or another coding agent and ask it to add X video downloads to your app. It gets working code for your stack, writes the integration and tests real calls with your API key, and your backend uses the same key. The steps are in Have your agent build Importly into your app.
FAQ
Can I download X videos with the official API?
Yes, if you have a developer account with read access. Request the post with media.fields=variants and download the highest-bitrate MP4 variant.
Why does my X video download work locally but fail on my server?
X is much stricter with traffic from cloud and datacenter IPs and unauthenticated clients. Code that works on your laptop often gets blocked or rate-limited once deployed. Importly works from servers and agent sandboxes.
Do twitter.com links still work?
Yes. Send either the x.com or the twitter.com link to the post.
Can I get just the audio?
Yes. Set includeVideo to false and you get the audio track only.
Related: Video downloader API, TikTok video download API, Supported sites, Importly docs.