TweetAPI Documentation

Use the TweetAPI REST API to retrieve public Twitter data, publish posts, and manage interactions.

Make your first request

Start with 100 one-time trial API units at 10 requests per minute. Most metered calls use one unit. You don't need a credit card or paid plan. Trial units do not expire.

1. Create a TweetAPI account. We'll set up your free API access automatically.
2. Open API Keys, select Create Key, give it a name, and save the full key. You can only see the full key when you create it. If you didn't save it, create another key.
3. Open the prefilled request below. Select your key and Try It! to look up a public profile. This request needs no separate X account authorization.
4. Look for 200 and a JSON object containing data. The Playground calls the real API and uses your API unit allowance.
5. Set the environment variable below and run an example in your own application.

Run the same request locally

Replace YOUR_API_KEY with the full key you saved. Set the variable in the terminal where you'll run your code. Keep keys on your server; never put them in frontend code or commit them to Git.

macOS / Linux:

export TWEETAPI_API_KEY='YOUR_API_KEY'

PowerShell:

$env:TWEETAPI_API_KEY = 'YOUR_API_KEY'

cURL (Bash)

curl --fail-with-body \
  'https://api.tweetapi.com/tw-v2/user/by-username?username=elonmusk' \
  -H "X-API-Key: ${TWEETAPI_API_KEY:?Set TWEETAPI_API_KEY first}"

Python SDK

Install the SDK with pip install tweetapi. Save this as quickstart.py and run python quickstart.py.

import os
from tweetapi import TweetAPI

client = TweetAPI(api_key=os.environ["TWEETAPI_API_KEY"])
user = client.user.get_by_username(username="elonmusk")
print(user["data"])

Node.js SDK (Node.js 18+)

Install the SDK with npm install tweetapi-node. Save this as quickstart.mjs and run node quickstart.mjs.

import TweetAPI from "tweetapi-node";

const apiKey = process.env.TWEETAPI_API_KEY;
if (!apiKey) throw new Error("Set TWEETAPI_API_KEY first");
const client = new TweetAPI({ apiKey });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data);

If your first request fails

• An unset variable or 401: set TWEETAPI_API_KEY to the full key, not the masked preview from the key list.
• Account setup still pending: use Check again on the setup screen. Contact support if access stays unavailable.
• 429: read the error message. For a per-minute limit, slow down and retry with bounded backoff; for exhausted allowance, check Billing.
• 503: the service is temporarily unavailable. Follow Retry-After when provided and use bounded retries.

Base URL

Send API requests to:

https://api.tweetapi.com/tw-v2/

Authentication

Include your API key in the X-API-Key header:

headers: {
  'X-API-Key': 'YOUR_API_KEY'
}

Before You Call the API

• Responses are JSON.
• Plan limits are enforced per TweetAPI account across its API keys: an API unit allowance and a per-minute request limit.
• Collection endpoints use cursor-based pagination where available.
• Posting, engagement, profile, DM, and X Chat endpoints can require account authorization fields in addition to your TweetAPI key. Check each endpoint page for the exact required parameters.
• A 429 response can mean that your subscription is inactive, available allowance and prepaid balance are exhausted, or you exceeded the per-minute limit. Inspect the error message before retrying. These responses do not include Retry-After or X-RateLimit-* headers.
• For a 503 response, follow the Retry-After header when present. Avoid repeated attempts if the error persists. Before retrying an action after an uncertain outcome, check whether it completed.

TweetAPI SDKs

The Python and Node.js SDKs include type support, automatic retries, and pagination.

Python

pip install tweetapi

from tweetapi import TweetAPI

client = TweetAPI(api_key="YOUR_API_KEY")
user = client.user.get_by_username(username="elonmusk")
print(user["data"]["followerCount"])

View on GitHub

Node.js / TypeScript

npm install tweetapi-node

import TweetAPI from "tweetapi-node";

const client = new TweetAPI({ apiKey: "YOUR_API_KEY" });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data.followerCount);

View on GitHub

Developer Resources

• OpenAPI specification for code generators and API tools.
• Full Postman collection for all 82 documented operations.
• Read-only Postman quick start with public profile, search, and tweet detail requests.

Key Features

• Retrieve public user profiles, tweets, followers, and engagement metrics
• Post tweets and manage likes, retweets, bookmarks, and direct messages
• Search tweets, users, and media with documented query parameters
• Fetch current posts, profiles, and metrics when your application sends a request
• Page through collections with cursors
• Work with images, videos, and GIFs

Available Endpoints

User Endpoints

• Get user by username
• Get user by ID
• Get multiple users by IDs
• Followers and following lists
• User tweets and replies
• Subscription information

Tweet Endpoints

• Tweet details and conversation threads
• Quote tweets and retweets
• Tweet translation
• Engagement metrics

Interaction Endpoints

• Create, reply, and delete posts
• Like and bookmark tweets
• Retweet and quote tweet
• List management

List & Community Endpoints

• List details and members
• Community information
• Timeline tweets

Search Endpoints

• Search tweets, users, and media
• Advanced search operators
• Filtering and sorting options

Plan Limits

The public plans currently have these per-minute request limits:

• Free: 10 requests per minute
• Pro: 60 requests per minute
• Ultra: 120 requests per minute
• Mega: 180 requests per minute

Private, legacy, or custom plan limits can differ. For a per-minute 429, use bounded exponential backoff and lower concurrency. If you've used up your plan's API unit allowance, check usage and subscription options in the dashboard. A short retry won't restore the allowance.

Pay-as-you-go fallback

Customers can make manual one-time PAYG purchases in Billing: 10,000 units for $5 USD, 20,000 for $10 USD, 40,000 for $20 USD, or 100,000 for $50 USD. Top-ups do not renew automatically. TweetAPI consumes an available free-plan or subscription allowance first, then uses a valid PAYG balance automatically. Canceling a subscription leaves valid PAYG units usable. Standalone PAYG access is limited to 60 requests per minute; an active plan with a higher rate limit keeps that higher limit.

PAYG units expire 365 days after successful payment settlement. When a top-up is applied, the whole still-valid wallet uses the later of its existing expiry and settlement plus 365 days. Already expired units are never restored. Payment before the old deadline alone does not guarantee an extension if the top-up is applied after the wallet expires. If you paid before expiry but application was delayed, contact support@tweetapi.com for review and correction or another appropriate remedy for confirmed processing errors. Billing and payment confirmations show the resulting expiry in UTC.

Units measure API usage, not the number of tweets returned. Most metered calls cost 1 unit; /tw-v2/xchat/send costs 10 and /tw-v2/auth/login costs 500. Metered responses with HTTP 200–499 are billable except 400, 401, 403, and 429. Billable empty results, pagination requests, and each separately submitted retry or repeated request use units.

Refunds revoke units proportionally, rounded up to whole units. Payment disputes revoke the entire related purchase's units, less units already revoked for refunds. A deficit locks PAYG, not an otherwise valid subscription. Top-ups repay a deficit before adding spendable units. Contact support@tweetapi.com about incorrect deductions, undelivered units, or payment disputes; buying more units is not a condition of requesting a remedy. See the terms and refund information. Mandatory rights are not limited.

Error Handling

TweetAPI uses standard HTTP status codes to indicate success or failure.

Common Error Codes

Error Response Format

All errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Invalid username parameter"
}

Best Practices

1. Check the response status code
2. Log error responses for debugging
3. Use exponential backoff for retries
4. Slow down when you hit a per-minute rate limit

Security Best Practices

• Never share your API key publicly or commit it to version control
• Rotate your keys regularly
• Use environment variables to store API keys in your applications
• Check usage in your dashboard for unusual activity

Support

For help, email support@tweetapi.com or contact @tweetapi on Telegram.