Download media

1 credit per fresh tweet processed with media · cache hits are free · All plans from $0.00012/credit

Use this endpoint to turn one tweet, or up to 50 tweet URLs or IDs, into a saved media gallery. The response gives a galleryUrl plus cache or bulk counts; it does not return per-file downloads, file metadata, or an uploaded mediaId.

curl -X POST https://xquik.com/api/v1/x/media/download \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "tweetInput": "1893456789012345678"
  }' | jq

Headers

x-api-key

string

required

Your API key. Session cookie authentication is also supported.

Content-Type

string

required

Must be application/json.

Body

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

tweetInput

string

Tweet URL or numeric tweet ID for a single download. Accepts x.com and twitter.com URL formats.

tweetId

string

Numeric tweet ID alias for tweetInput. Used when tweetInput is not provided.

tweetUrl

string

Tweet URL alias for tweetInput. Used when tweetInput and tweetId are not provided.

tweetIds

string[]

Array of tweet URLs or IDs for bulk download. Maximum 50 string items. Invalid IDs are skipped; the request fails only when no valid tweet IDs remain.

Media download handoff

Use this endpoint when your agent needs a saved gallery for tweet images, videos, or GIFs. Write one manifest row per request so downstream jobs can store the gallery link without treating it as an uploaded media ID or an individual media file URL.

Gallery URL

Store gallery_url from galleryUrl as the durable 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 invalid or failed IDs are skipped.

Input mode

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

Batch limit

Keep tweetIds at 50 items or fewer. Split larger backfills into multiple requests.

Write handoff

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

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

tweetId

string

Resolved tweet ID.

galleryUrl

string

Shareable gallery page URL with all downloaded media.

cacheHit

boolean

true if media was served from cache (no usage consumed).

{
  "tweetId": "1893456789012345678",
  "galleryUrl": "https://xquik.com/gallery/abc123",
  "cacheHit": false
}

galleryUrl

string

Combined gallery page URL containing media from all tweets.

totalTweets

number

Number of tweets processed.

totalMedia

number

Total media items downloaded across all tweets.

{
  "galleryUrl": "https://xquik.com/gallery/def456",
  "totalTweets": 3,
  "totalMedia": 7
}

{ "error": "invalid_input", "message": "Invalid request body" }

Missing, malformed, or non-JSON request body. Malformed JSON can also return invalid_json.

{ "error": "invalid_tweet_id", "message": "Tweet ID is empty or invalid" }

The provided tweet ID or URL could not be resolved to a valid tweet ID.

{ "error": "too_many_tweets", "message": "Max 50 tweets per request" }

The tweetIds array exceeds the 50-item limit. Split into multiple requests.

{ "error": "no_media", "message": "Tweet has no downloadable media" }

The tweet does not contain any images, videos, or GIFs.

{ "error": "unauthenticated", "message": "Missing or invalid API key" }

Missing or invalid API key / session cookie.

{ "error": "no_subscription", "message": "No active subscription" }

An active subscription or enough credits are required. Subscribe or top up from the dashboard.

{ "error": "tweet_not_found", "message": "Tweet not found" }

The tweet ID is valid, but the tweet cannot be fetched or no longer exists.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

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

{ "error": "x_api_unavailable" }

The read service returned an error. Retry after a short delay.

{ "error": "x_api_unavailable" }

Returned when you opt into the normalized v1 response contract and the read service is unavailable.

First download is metered and counts toward your monthly credit allowance. Subsequent requests for the same tweet return cached URLs at no cost (cacheHit: true). All downloads are saved to your gallery at https://xquik.com/gallery.

This endpoint supports dual authentication: API key (x-api-key header) or session cookie from the dashboard.Related: Get Tweet to look up tweet details and metrics, or use the xquik MCP tool for AI agent access.

Documentation Index

​Headers

​Body

​Media download handoff

Gallery URL

Single tweet

Bulk result

Input mode

Batch limit

Write handoff

​Response

Headers

Body

Media download handoff

Response