Skip to main content
POST https://xquik.com/api/v1/x/media/download Send 1 tweet ID or URL, or a list of them. The route downloads media from one tweet or a batch. Each response contains a gallery of photos, videos, and GIFs.
1 credit per fresh tweet processed with media · cache hits are freeAll plans from $0.00012/credit
This endpoint creates a saved media gallery from tweet URLs or IDs. The response gives a galleryUrl plus cache or bulk counts. It does not return per-file downloads, file metadata, or an uploaded mediaId.

Headers

Body

Use tweetIds for bulk downloads. If tweetIds holds at least 1 string value, the route uses bulk mode. In bulk mode it ignores single-tweet fields. Otherwise, use tweetInput, tweetId, or tweetUrl for a single tweet.

Save only chart posts

Send imageShows with the posts, & only the posts whose photos show it get saved.
  • imageFilter.unchecked lists posts without a safe photo & posts X can’t find. They cost nothing.
  • When no photo shows it, nothing is saved & nothing is billed. A single download answers with empty items. A bulk download answers with totalTweets 0.

Media download handoff

Your agent may need a saved gallery for tweet images, videos, or GIFs. If so, use this endpoint. Write one manifest row per request. Later jobs can then store the gallery link. It is not an uploaded media ID or an individual media file URL.

Gallery URL

Store gallery_url from galleryUrl as the link for downloaded media.

Single tweet

Store requested_tweet_id, tweet_id, and cache_hit. cacheHit: true means the single-tweet request used cached media and is free.

Bulk result

Store requested_tweet_ids, successful_tweet_count from totalTweets, and media_item_count from totalMedia. totalTweets counts successful tweets with media after the route skips invalid or failed IDs.

Input mode

Send tweetIds for bulk. When it contains at least 1 string, bulk mode ignores tweetInput, tweetId, and tweetUrl.

Posts left over

A long tweetIds list saves what fits in the call’s time. Send the posts in unprocessedTweetIds again. They cost nothing.

Write handoff

This endpoint creates a gallery download, not an uploaded media ID. Use Upload Media before DMs or hosted tweet assets.

Store a tweet media download manifest

Keep one manifest row per single or bulk request. A gallery URL represents the download result. A gallery URL is neither an uploaded media ID nor a direct asset URL.Use these outcomes when reconciling a download request.
  • cacheHit: true confirms a free cached single result.
  • cacheHit: false confirms a fresh single result.
  • If totalTweets is below the valid input count, review skipped Tweet IDs.
  • A 400 no_media response means the source tweet has no downloadable media.
  • Keep rejected inputs while processing valid Tweet IDs.
  • Send unprocessedTweetIds again until the answer has none.
Fresh downloads cost 1 credit per tweet processed with media. Cached single downloads return cacheHit: true and are free. Bulk responses do not return freshCount. Store the request IDs with totalTweets and totalMedia for reconciliation.

Response

200 OK (single)

200 OK (bulk)

400 Invalid input

{ "error": "invalid_input", "message": "Invalid request body" } Missing, malformed, or non-JSON request body. Malformed JSON can also return invalid_json.

400 Invalid tweet ID

{ "error": "invalid_tweet_id", "message": "Tweet ID is empty or invalid" } Xquik could not resolve the provided tweet ID or URL to a valid ID.

400 No media

{ "error": "no_media", "message": "Tweet has no downloadable media" } The tweet does not contain any images, videos, or GIFs.

401 Unauthenticated

{ "error": "unauthenticated", "message": "Missing or invalid API key" } Supply a valid API key or OAuth bearer token.

402 Insufficient credits

The available balance cannot cover the download. Top up or subscribe from the dashboard billing page.

404 Tweet not found

{ "error": "tweet_not_found", "message": "Tweet not found" } The tweet ID is valid. Xquik cannot fetch that tweet, or it no longer exists.

429 Rate limit exceeded

The API key, user, or plan tier is sending requests too fast. Respect the Retry-After header before retrying.

502 X API unavailable

The read service failed. Retry after a short delay.

424 Dependency failed

The opt-in normalized contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.

X (Twitter) media downloader questions

How do I download X (Twitter) media?

Copy the tweet link or numeric ID. Send it through tweetInput. The gallery can contain Twitter videos and GIFs plus images.

Can I save Twitter videos or GIFs on a phone?

Yes. Open the returned galleryUrl in a web browser. The API does not return direct per-file URLs.

Does this work like a browser extension?

No. This is a server-side API. Keep the API key or bearer token server-side.

Can I download X (Twitter) video files directly?

No. This route creates a gallery. It does not expose per-file downloads or resolution controls.

Can I download media from many tweets?

Yes. Send the tweet IDs through tweetIds. The response returns one gallery with tweet and media counts.
Xquik meters the first download against your monthly credit allowance. Later requests for the same tweet return cached URLs at no cost (cacheHit: true). Xquik saves all downloads to your gallery at https://xquik.com/gallery.
This endpoint accepts an API key or OAuth bearer token. Keep either credential server-side.Related. Get Tweet to look up tweet details and metrics. For AI agent access, use the execute MCP tool.

Response examples

  • 400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 404 { "error": "tweet_not_found", "message": "Tweet not found." }
  • 424 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 502 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }