X / Twitter User Media API

Get an X (Twitter) account's photo and video tweets — the Media tab — with image URLs, MP4 video URLs, dimensions, and alt text. JSON, $0.01 per call.

POST/v1/twitter/user-media

$0.01/call

Returns the Media tab of an X profile: tweets that contain photos, videos, or GIFs. Each item's media array has the full-size image URL, the MP4 video_url for videos and GIFs, duration, dimensions, and alt text.

Usage

const res = await fetch('https://api.yepapi.com/v1/twitter/user-media', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"username": "NASA", "count": 20}),
});
const { data } = await res.json();
console.log(data);

curl -X POST https://api.yepapi.com/v1/twitter/user-media \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "NASA", "count": 20}'

import requests

res = requests.post(
    "https://api.yepapi.com/v1/twitter/user-media",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"username": "NASA", "count": 20},
)
print(res.json()["data"])

Request Body

Parameter	Type	Required	Description	Default
`username`	`string`	One of	X handle — `NASA`, `@NASA`, or an x.com / twitter.com profile URL	—
`user_id`	`string`	One of	Numeric X user ID (skips the username lookup). Send `username` or `user_id`	—
`count`	`number`	No	Page size hint, 1–100	`20`
`cursor`	`string`	No	`cursor` from the previous response, to fetch the next page	—

Response

{
  "ok": true,
  "data": {
    "cursor": "DAABCgABHV69S9c__-4KAAIdVTZJU9cQiwgAAwAAAAIAAA",
    "tweets": [
      {
        "author": {
          "avatar": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
          "banner": "https://pbs.twimg.com/profile_banners/11348282/1788992290",
          "created_at": "2007-12-19T20:20:32+00:00",
          "description": "Making the seemingly impossible, possible. ✨",
          "followers_count": 92298687,
          "following_count": 115,
          "id": "11348282",
          "is_blue_verified": true,
          "likes_count": 17049,
          "listed_count": 96842,
          "location": "Pale Blue Dot",
          "media_count": 28221,
          "name": "NASA",
          "pinned_tweet_ids": [
            "2116263878807998722"
          ],
          "protected": false,
          "tweet_count": 74477,
          "url": "https://x.com/NASA",
          "username": "NASA",
          "verified": false,
          "verified_type": null,
          "website": "http://www.nasa.gov/"
        },
        "bookmarks": 29,
        "conversation_id": "2116263878807998722",
        "created_at": "2026-10-30T20:20:01+00:00",
        "hashtags": [],
        "id": "2116263878807998722",
        "in_reply_to_tweet_id": null,
        "in_reply_to_username": null,
        "is_quote": false,
        "is_retweet": false,
        "lang": "en",
        "likes": 681,
        "media": [
          {
            "alt_text": "Three jet aircraft, each with a white nose and blue body, fly in a triangle formation against a clear blue sky. White trails follow each jet. ",
            "duration_ms": null,
            "height": 1280,
            "type": "photo",
            "url": "https://pbs.twimg.com/media/HV56yHnXcAAwYJ2.jpg",
            "video_url": null,
            "width": 1920
          }
        ],
        "mentions": [],
        "possibly_sensitive": false,
        "quoted_tweet": null,
        "quotes": 4,
        "replies": 38,
        "retweeted_tweet": null,
        "retweets": 86,
        "text": "MAX POWER, America’s newest aerospace expo and air show, is just a week away!\n\nThis showcase will be packed with events—from aircraft flyovers to a chance to meet NASA astronauts and experts. Here's w…",
        "url": "https://x.com/NASA/status/2116263878807998722",
        "urls": [
          "https://go.nasa.gov/4zjj9BD"
        ],
        "views": 202236
      }
    ]
  }
}

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.tweets`	`object[]`	Tweets, newest first
`data.tweets[].id`	`string`	Tweet ID
`data.tweets[].url`	`string`	x.com URL of the tweet
`data.tweets[].text`	`string`	Full text
`data.tweets[].created_at`	`string`	ISO 8601 timestamp
`data.tweets[].lang`	`string \| null`	Language code detected by X
`data.tweets[].author`	`object`	Author profile — same fields as `/v1/twitter/user`
`data.tweets[].likes`	`number`	Like count
`data.tweets[].retweets`	`number`	Repost count
`data.tweets[].replies`	`number`	Reply count
`data.tweets[].quotes`	`number`	Quote count
`data.tweets[].bookmarks`	`number`	Bookmark count
`data.tweets[].views`	`number \| null`	View count
`data.tweets[].conversation_id`	`string`	ID of the thread's first tweet
`data.tweets[].in_reply_to_tweet_id`	`string \| null`	Tweet this one replies to
`data.tweets[].in_reply_to_username`	`string \| null`	Handle this one replies to
`data.tweets[].is_retweet`	`boolean`	This is a repost — the original is in `retweeted_tweet`
`data.tweets[].is_quote`	`boolean`	This quotes another tweet — see `quoted_tweet`
`data.tweets[].possibly_sensitive`	`boolean`	Flagged as sensitive media
`data.tweets[].hashtags`	`string[]`	Hashtags without `#`
`data.tweets[].mentions`	`string[]`	Mentioned handles
`data.tweets[].urls`	`string[]`	Expanded links
`data.tweets[].media`	`object[]`	Photos, videos, GIFs: `type` (`photo`, `video`, `animated_gif`), `url`, `video_url` (MP4), `duration_ms`, `width`, `height`, `alt_text`
`data.tweets[].quoted_tweet`	`object \| null`	The quoted tweet, same shape
`data.tweets[].retweeted_tweet`	`object \| null`	The reposted tweet, same shape
`data.cursor`	`string \| null`	Cursor for the next page

Pagination

Each response includes a cursor. Send the same request again with that value in cursor to get the next page; cursor is null when there is nothing more (or the page came back empty). count is a page-size hint — X may return a few more or fewer items than you ask for. Every page is a separate $0.01 call.

Caching

Responses are cached for 10 minutes.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	Neither `username` nor `user_id` was sent, or one is malformed
`404`	`NOT_FOUND`	User not found or suspended
`429`	`RATE_LIMITED_UPSTREAM`	Too many requests in a short burst — retry after a few seconds
`502` / `503`	`UPSTREAM_ERROR` / `SERVICE_UNAVAILABLE`	Temporary problem fetching data from X — retry later

Failed calls are not charged.

A protected account, or one with nothing to show, returns 200 with an empty tweets list.

Twitter User API — the account's profile and counts
Tweet Replies API — replies to any of these tweets
Twitter Search API — from:<username> plus any other operator

X / Twitter User Media API

On this page