Docs/X Posts
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
| Name | Type | Requirement | Description |
|---|---|---|---|
| username | string | Required | X username without @. 1-50 characters. |
| limit | number | Optional | Posts 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
| Field | Type | Description |
|---|---|---|
| username / count | string / number | Requested username and number of posts returned. |
| tweets[] | array | Post rows. See the fields below. |
| id / text / created_at / lang / url | string | Post identity, text, X's created_at string, language, and permalink. |
| likes / retweets / replies / quotes / bookmarks / views | number | Each has a *_status field: present, not_exposed, or parser_miss. Optional: a metric X hides is omitted, never zero. |
| author | object | id, username, name, verified, blue_verified, profile_image_url. |
| media[] / hashtags[] / urls[] / mentions[] | array | Attachments (type, url, preview_url), hashtags, links (url, display_url, expanded_url), and mentioned usernames. Always present; empty when none. |
| is_reply / is_retweet / is_quote | boolean | Post 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_fetched | boolean / string / number | complete 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_ago | string / number | Optional: 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
}