🐦 X (Twitter) API: Real-Time Tweets, Users, Lists & Trends Over HTTP

Call X (formerly Twitter) data like any REST API. This X API is an always-on Apify Standby Actor: send a GET request, get JSON back in seconds. No runs to start, no datasets to poll, no X developer account.

Search tweets, look up profiles, page through followers, replies, retweeters, list members and trending topics. All through 15 simple endpoints.

💰 Pricing: $0.004 per successful request | ⚡ Response: live JSON, seconds | 🔓 No X login or API key

---

📋 Table of Contents

1. How It Works
2. Quick Start
3. Pricing
4. Endpoints
5. Pagination
6. Response Format
7. Errors & Status Codes
8. Code Examples
9. Free Plan
10. Related Actors
11. FAQ
12. Contact

---

🧭 How It Works

This Actor runs in Apify Standby mode. Instead of starting a run and waiting for a dataset, you call an HTTP endpoint and get the result in the response.

	Classic Actor run	This X API (Standby)
How you call it	Start a run, wait, read the dataset	Plain GET request
Latency	Run startup + scraping	Live response, no startup
Result	Dataset items	JSON in the HTTP response
Billing	Per run / per item	Per request
Best for	Large batch jobs	Apps, bots, agents, dashboards

Every endpoint returns one object or one page of results. Use the cursor to get the next page.

---

🚀 Quick Start

1. Get your Apify API token from Console → Settings → API & Integrations.

2. Call an endpoint:

curl "https://apidojo--x-api.apify.actor/handle/elonmusk" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"

3. Get JSON back:

{
  "status": 200,
  "message": "OK",
  "data": {
    "type": "user",
    "userName": "elonmusk",
    "id": "44196397",
    "name": "Elon Musk",
    "followers": 1728,
    "...": "..."
  }
}

That's it. That request cost $0.004.

Authentication: send your Apify token in the Authorization: Bearer <token> header (recommended) or as a ?token=<token> query parameter. Your token is never forwarded to the upstream service.

---

💰 Pricing

One flat price, every endpoint.

Event	Price	When it fires
Request (request-event)	$0.004 per call	Every successful request that returns data

• Same price for every endpoint. A profile lookup and a page of 20 search results cost the same.
• You only pay for successful responses. Invalid requests (400), not-found results, rate-limit refusals and upstream errors are not charged.
• No platform fees, no compute units, no runs. Just the per-request price.

Cost Examples

Scenario	Requests	Cost
Look up 1 profile	1	$0.004
Fetch 100 tweets by ID	100	$0.40
Search a keyword, 50 pages deep	50	$0.20
Look up 1,000 profiles	1,000	$4.00
10,000 calls in a month	10,000	$40.00

Paginated endpoints are charged per page. Following a cursor is a new request, so 10 pages = 10 requests = $0.04.

---

📚 Endpoints

All endpoints are GET. Base URL: https://apidojo--x-api.apify.actor

👤 Users

Endpoint	Description	Params
/handle/{handle}	Full profile by handle	handle (e.g. elonmusk)
/handle/{handle}/about	"About this account" data: country, account source, username changes, verified since	handle
/user/{id}	Full profile by user ID	id (e.g. 44196397)
/user/{id}/tweets	A user's tweets	id, cursor
/user/{id}/replies	A user's replies	id, cursor
/user/{id}/followers	A user's followers	id, cursor
/user/{id}/followings	Accounts a user follows	id, cursor
/search/users	Search users by keyword	query (required), cursor

🐦 Tweets

Endpoint	Description	Params
/search	Search tweets, supports X advanced search operators	query (required), sort (Latest or Top), cursor
/tweet/{id}	Full tweet by ID, including quotes, retweets, media and articles	id
/tweet/{id}/replies	Replies to a tweet	id, cursor
/tweet/{id}/retweeters	Users who retweeted a tweet	id, cursor

📃 Lists

Endpoint	Description	Params
/list/{id}/tweets	Tweets from a list	id, cursor
/list/{id}/members	Members of a list	id, cursor

📈 Trends

Endpoint	Description	Params
/trends	Trending topics for a country	country (required, two uppercase letters, e.g. US, GB)

Tip: The list ID is the last part of the list URL. In https://x.com/i/lists/78783491 the ID is 78783491.

The full OpenAPI spec is available on the Actor's API tab in Apify Console.

---

🔄 Pagination

Paginated endpoints return a cursor with each page. Pass it back to get the next page.

# Page 1
curl "https://apidojo--x-api.apify.actor/search?query=apify&sort=Latest" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"

# Page 2
curl "https://apidojo--x-api.apify.actor/search?query=apify&sort=Latest&cursor=CURSOR_FROM_PAGE_1" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"

Stop when the response has no cursor or the page comes back empty. Each page is one request ($0.004).

---

📊 Response Format

Every response has the same envelope:

{
  "status": 200,
  "message": "OK",
  "data": { }
}

Endpoint type	data contains
Single profile / tweet / about	One object
Tweet lists (search, user tweets, replies, list tweets)	{ "tweets": [...], "cursor": "..." }
User lists (followers, followings, retweeters, user search)	{ "users": [...], "cursor": "..." }
List members	{ "tweets": [...] } (array of user objects)
Trends	Array of trend objects

Tweet Object

{
  "type": "tweet",
  "id": "1757983181972930764",
  "url": "https://x.com/ESPNStatsInfo/status/1757983181972930764",
  "twitterUrl": "https://twitter.com/ESPNStatsInfo/status/1757983181972930764",
  "text": "Anthony Davis and Rui Hachimura are the 1st @Lakers duo with 35 points each...",
  "retweetCount": 58,
  "replyCount": 10,
  "likeCount": 158,
  "quoteCount": 8,
  "viewCount": 41230,
  "bookmarkCount": 7,
  "createdAt": "Thu Feb 15 04:20:26 +0000 2024",
  "lang": "en",
  "isReply": false,
  "isRetweet": false,
  "isQuote": false,
  "media": ["https://pbs.twimg.com/media/GGWb69-a0AAj1iA.jpg"],
  "author": {
    "type": "user",
    "userName": "ESPNStatsInfo",
    "id": "53120768",
    "name": "ESPN Stats & Info",
    "isVerified": true,
    "followers": 1828908,
    "following": 61
  }
}

Tweets can also include quote, retweet, extendedEntities and article (title, preview text, cover image and content blocks for X articles).

User Object

Key fields: id, userName, name, url, description, location, followers, following, listedCount, statusesCount, mediaCount, favouritesCount, isVerified, protected, profilePicture, coverPicture, createdAt, canDm.

About Object

accountBasedIn, locationAccurate, accountSource, accountCreatedAt, usernameChangeCount, usernameLastChangedAt, verifiedSince, avatarUrl, profileImageShape.

Trend Object

name, url, query, tweetVolume, promotedContent.

---

⚠️ Errors & Status Codes

Errors use the same envelope, without data. Requests that return no data are not charged.

Status	Meaning	Charged?
200	Success	✅ $0.004
400	Invalid parameters. errors lists what's wrong	❌
404	Unknown endpoint or nothing found	❌
403	Access not available on your plan or account	❌
429	Monthly free request limit reached	❌
502	Upstream error, safe to retry	❌
503	Plan check temporarily unavailable, retry shortly	❌

Example 400:

{
  "status": 400,
  "message": "Bad request",
  "errors": ["query.country: country must be a two-letter uppercase code (e.g. US, GB)"]
}

---

💻 Code Examples

cURL

curl "https://apidojo--x-api.apify.actor/tweet/1859663799319769336" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"

Python

import requests

BASE = "https://apidojo--x-api.apify.actor"
HEADERS = {"Authorization": "Bearer YOUR_APIFY_TOKEN"}

def search_tweets(query, pages=5):
    tweets, cursor = [], None
    for _ in range(pages):
        params = {"query": query, "sort": "Latest"}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(f"{BASE}/search", headers=HEADERS, params=params, timeout=300).json()
        data = res.get("data") or {}
        tweets += data.get("tweets", [])
        cursor = data.get("cursor")
        if not cursor or not data.get("tweets"):
            break
    return tweets

print(len(search_tweets("from:apify", pages=3)))  # max 3 requests = $0.012

JavaScript / Node.js

const BASE = 'https://apidojo--x-api.apify.actor';
const headers = { Authorization: `Bearer ${process.env.APIFY_TOKEN}` };

const res = await fetch(`${BASE}/handle/elonmusk`, { headers });
const { data: user } = await res.json();

const followers = await fetch(`${BASE}/user/${user.id}/followers`, { headers }).then((r) => r.json());
console.log(followers.data.users.length, followers.data.cursor);

Trending Topics

curl "https://apidojo--x-api.apify.actor/trends?country=US" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"

---

🆓 Free Plan

Apify Free plan users can try this API with a limited number of free requests each month. When the monthly limit is reached, the API answers 429 until the next month. Subscribe to a paid Apify plan for unlimited requests.

---

🌴 Related Actors

Need bulk exports to a dataset, CSV or Excel instead of live calls? Use our batch scrapers:

Tool	Best For
🐦 Tweet Scraper	Large keyword, hashtag and profile tweet exports
⚡ Twitter Scraper Lite	Smaller, quick tweet searches
👤 Twitter User Scraper	Bulk profiles, followers and followings
🏯 Twitter List Scraper	Bulk list tweets and members
💬 Twitter Replies Scraper	Full reply threads
🪪 Twitter Profile Scraper	Profile timelines

---

❓ Frequently Asked Questions

What is a Standby Actor?

A Standby Actor is an always-running web server on Apify. You call it over HTTP like any API and get the response directly. No runs to start or datasets to read. Learn more.

How much does it cost?

$0.004 per successful request, the same for every endpoint. 1,000 requests = $4. Failed and invalid requests are free.

Am I charged per tweet or per request?

Per request. A page of search results costs the same as a single profile lookup.

Do I need an X (Twitter) developer account?

No. You only need an Apify API token.

How do I get more than one page of results?

Pass the cursor from the previous response as a query parameter. Each page is a separate $0.004 request. See Pagination.

Can I use X advanced search operators?

Yes. /search accepts the same query syntax as X search, e.g. from:elonmusk since:2025-01-01 min_faves:100. Test your query on X first. The API returns what X returns and adds no extra filtering.

How fast is it?

Responses come back live, usually within seconds. There is no run startup time.

Can I use it from an AI agent or bot?

Yes. It's a plain HTTP API with an OpenAPI spec, so it fits LLM tool calls, bots, backends and no-code tools that can make HTTP requests.

Where is the data stored?

Nowhere. Results are returned in the HTTP response only. For dataset, CSV or Excel exports, use one of the batch scrapers.

Can I access private accounts or lists?

No. Only publicly available data is returned.

---

📞 Contact

If you need any sort of support, please send an email to apidojo10@gmail.com. You name it, we get it.

---

Ready to call X data like an API? One endpoint per question, $0.004 per answer, live JSON in seconds. Grab your Apify token and send your first request. 🐦