X (Twitter) Tweet Scraper API

Search X posts, retrieve individual Tweets, and collect Tweets from public profiles in one batch-friendly Apify Actor. Every successful Tweet is stored as one Dataset item with normalized text, author details, engagement metrics, media URLs, and input attribution.

Overview

The Actor supports three ways to discover the same business object—a Tweet:

• Search mode: keywords, hashtags, or native X search queries
• Tweet detail mode: x.com/twitter.com status URLs or numeric Tweet IDs
• User Tweets mode: usernames, @usernames, or profile URLs

Inputs can be mixed in a single run. A failed input produces a structured error item and does not stop other inputs.

Features

• X search with Top, Latest, or Media results
• Cursor-based search and profile pagination
• Batch inputs across all three modes
• Complete Tweet text, including Note Tweet/long-form text when exposed by X
• Author metadata and engagement counts
• All photos and video variants, including highest-bitrate MP4 selection
• Quote, retweet, and reply metadata
• Tweet and cursor deduplication
• Per-input errors that distinguish invalid input, not found, private, suspended, blocked, rate limited, no data, timeout, proxy, and parsing failures
• One Dataset item per successful Tweet
• Pay-per-result charging only after a successful Tweet item is stored

Use cases

• Brand and topic research
• News and trend collection
• Public profile content analysis
• Social datasets for analytics and AI pipelines
• Tweet URL enrichment
• Scheduled research and Dataset exports

Input

At least one of searchQueries, tweetUrls, or profiles must contain a value. All three may be provided together.

Field	Type	Default	Description
searchQueries	string[]	—	Keywords, hashtags, or search expressions; up to 1,000
sort	enum	top	top, latest, or media for Search inputs
profiles	string[]	—	Usernames, @usernames, or profile URLs; up to 1,000
tweetUrls	string[]	—	X/Twitter Tweet URLs or numeric Tweet IDs; up to 1,000
maxResults	integer	15	Maximum Tweets per Search or profile input; schema max 190

maxResults applies per Search query or profile. Free users receive up to 15 results per input. Starter, Scale, and Business users receive up to 190. Every Tweet URL/ID returns at most one Tweet.

Search mode

Add one or more values to searchQueries. Simple keywords and hashtags work directly. Search type is a selectable field:

• top: relevant Tweet results
• latest: recent Tweet results
• media: Tweet results containing media

People and Lists search are intentionally outside this Tweet-only Actor. Their labels describe non-Tweet search categories, while the upstream endpoint returned Tweet-shaped timeline items in live validation rather than People/List objects, so exposing them would give users misleading semantics.

{
  "searchQueries": ["OpenAI", "#AI"],
  "sort": "latest",
  "maxResults": 15
}

Tweet detail mode

Supported forms include:

• https://x.com/status_is_down/status/2034694288651473335
• https://twitter.com/status_is_down/status/2034694288651473335
• 2034694288651473335

URLs are normalized to https://x.com/{username}/status/{tweetId}. For an ID-only input, the canonical URL is built from the returned author when available.

{
  "tweetUrls": ["https://x.com/status_is_down/status/2034694288651473335", "2034694288651473335"]
}

User Tweets mode

Supported profile forms include OpenAI, @OpenAI, https://x.com/OpenAI, and https://twitter.com/OpenAI.

The Actor normalizes every supported form to a screen name and automatically paginates the public post timeline. Pinned posts are excluded so the results remain chronological.

{
  "profiles": ["@OpenAI", "https://x.com/OpenAIDevs"],
  "maxResults": 15
}

Mixed input example

{
  "searchQueries": ["OpenAI"],
  "tweetUrls": ["2034694288651473335"],
  "profiles": ["@OpenAI"],
  "maxResults": 15,
  "sort": "latest"
}

Output

Each successful Tweet is one Dataset item. Top-level convenience fields make the Dataset, CSV, and Excel exports useful immediately; nested objects preserve structured API data.

Success example

{
  "inputType": "search",
  "inputValue": "OpenAI",
  "normalizedInput": "OpenAI",
  "success": true,
  "status": "success",
  "tweetId": "1234567890123456789",
  "url": "https://x.com/example/status/1234567890123456789",
  "text": "Tweet text...",
  "createdAt": "2026-09-02T10:00:00.000Z",
  "language": "en",
  "authorId": "12345",
  "authorUsername": "example",
  "authorName": "Example",
  "authorVerified": false,
  "likesCount": 100,
  "repliesCount": 10,
  "retweetsCount": 20,
  "quotesCount": 5,
  "bookmarksCount": 3,
  "viewsCount": 10000,
  "conversationId": "1234567890123456789",
  "isReply": false,
  "isRetweet": false,
  "isQuote": false,
  "inReplyToTweetId": null,
  "inReplyToUsername": null,
  "author": {
    "id": "12345",
    "username": "example",
    "name": "Example",
    "followersCount": 10000,
    "followingCount": 200
  },
  "engagement": {
    "likes": 100,
    "replies": 10,
    "retweets": 20,
    "quotes": 5,
    "bookmarks": 3,
    "views": 10000
  },
  "media": {
    "photos": [],
    "videos": []
  },
  "hashtags": [],
  "mentions": [],
  "urls": [],
  "quotedTweet": null,
  "retweetedTweet": null,
  "scrapedAt": "2026-09-02T10:01:00.000Z"
}

Fields not exposed by X are returned as null or empty arrays; values are not invented.

Error example

{
  "inputType": "profile",
  "inputValue": "@missing_example",
  "normalizedInput": "missing_example",
  "success": false,
  "status": "not_found",
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested X profile could not be found.",
    "retryable": false
  },
  "scrapedAt": "2026-09-02T10:01:00.000Z"
}

Error items are not charged.

Pricing

You pay only for successfully returned Tweets. There is no query fee and no start fee. Empty results, failed inputs, errors, duplicates, and non-Tweet search objects are not charged.

Apify plan	Price per 1,000 successful Tweets
Free	$0.30
Starter	$0.25
Scale	$0.22
Business	$0.20

Prices start from $0.20 per 1,000 successfully returned Tweets.

Limits

• Free: up to 15 Tweets per Search or profile input.
• Starter, Scale, and Business: up to 190 Tweets per Search or profile input.
• Tweet detail inputs return at most one Tweet each.
• The Actor stops as soon as the requested result limit is reached. Missing or repeated pagination cursors also stop collection safely.

API usage

Start a run with the Apify API:

curl -X POST "https://api.apify.com/v2/acts/USERNAME~x-tweet-scraper-api/runs?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries":["OpenAI"],"sort":"top","maxResults":15}'

Replace USERNAME and APIFY_TOKEN with your own values. You can also call the Actor from the Apify JavaScript/Python clients, schedules, webhooks, or integrations.

Dataset

The default Dataset overview prioritizes status, input attribution, Tweet text, author, creation time, engagement, views, and canonical Tweet URL. JSON exports also contain nested author, engagement, media, quote, and retweet objects.

Automation

Use Apify schedules to run recurring searches or profile collection. Use webhooks to notify downstream systems, and export Dataset items as JSON, CSV, Excel, XML, RSS, or JSONL using Apify storage APIs.

Limitations

• X and upstream response structures can change without notice.
• Public profiles and public Tweets are the intended scope. Private, suspended, deleted, age-gated, region-restricted, or otherwise unavailable content may not be retrievable.
• Historical search depth and result ordering are controlled by X and are not guaranteed.
• Engagement and view counts reflect the values X returns at scrape time.

Legal and compliance

Use this Actor only for lawful purposes. Respect applicable laws, privacy rights, intellectual-property rights, contractual obligations, and X's terms and policies. Collect only data you are authorized to process, avoid sensitive-personal-data misuse, and configure retention and access controls appropriate to your use case.

Support

When reporting a problem, include the Actor run ID, input type, status/error code, and approximate time. Do not send X cookies, authentication tokens, proxy passwords, or other secrets in support messages.