Twitter Media Status API | Check Upload Readiness

Media Status returns the async processing state of an uploaded media_id, so you can confirm a video, GIF, or large image finished processing before you attach it to a tweet. It is a single $0.0008 read with bearer auth, returning the current state, a suggested retry delay, and the progress percentage.

curl -X GET "https://example.com/media/status?media_id=1899999999999999999&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"

{  "media_id": "1899999999999999999",  "state": "succeeded",  "check_after_secs": 0,  "progress_percent": 100}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use it after Upload Media to poll a media_id until state is succeeded, then call Create Tweet. Small images return succeeded immediately; videos, GIFs, and large media process asynchronously and need this check before they can be attached.

Notes

• Requires a registered session for the acting account (POST /twitter/customer/session).
• media_id is the value returned by POST /twitter/media/upload.

Related endpoints

• Upload Media: Upload an image and get a media_id to attach to a tweet.
• Like Tweet: Like (favorite) a tweet on behalf of an authenticated account.

FAQ

How do I know when an uploaded media_id is ready?

Poll GET /twitter/media/status with the media_id. When state is succeeded the media is ready to attach to a tweet; while it is pending or in_progress, wait check_after_secs seconds and poll again.

Do images need a status check?

Small images usually return succeeded on the first check, so one call is enough. Videos, GIFs, and large media process asynchronously, so poll until state is succeeded before creating the tweet.

What does a failed state mean?

Processing failed upstream and the media_id cannot be attached. The error field carries the reason; upload the media again to get a fresh media_id.