Docs / API reference

POST/v1/data/twitter/tweets

X Posts

Get recent posts from an X user with text, engagement metrics, media, hashtags, links, and mentions.

Execution model

Live request

Runtime depends on endpoint, target, pagination, rendering mode, and active plan limits.

Credit weight

Live catalog

Current weights are managed from the Data API Weights admin table and shown on pricing before use.

Parameters

NameTypeRequirementDescription
usernamestringRequiredX username without @. 1-50 characters.
limitnumberOptionalPosts to return (1-3200). Up to 40 returns immediately from the public timeline page. Above 40 runs as a queued job: the response is HTTP 202 with job_id and status_url.

Response fields

FieldTypeDescription
username / countstring / numberRequested username and number of posts returned.
tweets[]arrayPost rows. See the fields below.
id / text / created_at / lang / urlstringPost identity, text, X's created_at string, language, and permalink.
likes / retweets / replies / quotes / bookmarks / viewsnumberEach has a *_status field: present, not_exposed, or parser_miss. Optional: a metric X hides is omitted, never zero.
authorobjectid, username, name, verified, blue_verified, profile_image_url.
media[] / hashtags[] / urls[] / mentions[]arrayAttachments (type, url, preview_url), hashtags, links (url, display_url, expanded_url), and mentioned usernames. Always present; empty when none.
is_reply / is_retweet / is_quotebooleanPost kind. Reply, retweet and quote IDs (in_reply_to_*, retweeted_tweet_id, retweeted_tweet, quoted_tweet_id) appear only when they apply.
complete / stop_reason / coverage / pages_fetchedboolean / string / numbercomplete is true only when the source was exhausted. The public page stops with guest_page_limit and coverage ranked_public_sample.
oldest_tweet_at / newest_tweet_at / reached_days_agostring / numberOptional: time window covered by the returned posts; omitted when no post has a readable date.

Request and response

curl -X POST "https://api.datablue.dev/v1/data/twitter/tweets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "nasa",
  "limit": 20
}'
Example response
{
  "success": true,
  "time_taken": 3.47,
  "username": "nasa",
  "count": 1,
  "tweets": [
    {
      "id": "1850000000000000001",
      "text": "A new image from the James Webb Space Telescope.",
      "text_complete": true,
      "created_at": "Mon Nov 10 15:00:00 +0000 2026",
      "likes": 24000,
      "likes_status": "present",
      "retweets": 4800,
      "retweets_status": "present",
      "replies": 320,
      "replies_status": "present",
      "quotes": 180,
      "quotes_status": "present",
      "bookmarks": 900,
      "bookmarks_status": "present",
      "views": 1200000,
      "views_status": "present",
      "lang": "en",
      "url": "https://x.com/NASA/status/1850000000000000001",
      "author": {
        "id": "11348282",
        "username": "NASA",
        "name": "NASA",
        "blue_verified": true,
        "profile_image_url": "https://pbs.twimg.com/profile_images/example_400x400.jpg"
      },
      "media": [
        {
          "type": "photo",
          "url": "https://pbs.twimg.com/media/example.jpg"
        }
      ],
      "hashtags": [
        "JWST"
      ],
      "urls": [],
      "mentions": [],
      "conversation_id": "1850000000000000001",
      "is_reply": false,
      "is_retweet": false,
      "is_quote": false
    }
  ],
  "stop_reason": "guest_page_limit",
  "coverage": "ranked_public_sample",
  "pages_fetched": 1,
  "oldest_tweet_at": "Mon Nov 10 15:00:00 +0000 2026",
  "newest_tweet_at": "Mon Nov 10 15:00:00 +0000 2026",
  "reached_days_ago": 3.1
}