# TweetAPI /tw-v2 Public API Quick Reference for AI Agents
Generated deterministically from the maintained public contract sources
Version: 2.0
Total Endpoints: 92

Scope: This export lists all 92 documented public /tw-v2 operations, required request fields, one cURL example, and usage costs. For full request constraints (including enums, defaults, ranges, and array forms), success and error response schemas, and JSON examples, use https://tweetapi.com/openapi-v2.json. Match an operation by HTTP method and path. Endpoint guides are linked below.

================================================
QUICK REFERENCE
================================================

Base URL: https://api.tweetapi.com/tw-v2
Overview: Product facts, SDK packages, and hosted MCP setup are in https://tweetapi.com/llms.txt.
Authentication: All requests require the X-API-Key header. An API key does not replace an X account authToken or login credentials required by an operation.
Rate limits: Requests are limited per rolling second and shared by a TweetAPI account across its API keys: 2/second on Free, 20 on PAYG and Pro, 30 on Ultra, 40 on Mega, 50 on Giga, and 60 on Tera. Writes (posts, replies, likes, follows, DMs, profile and list changes) also have a per-minute limit: 60 on Pro, 120 on Ultra, 180 on Mega, 300 on Giga, and 500 on Tera. Each plan caps requests in progress at once at three seconds of its rate. Private, legacy, and custom limits can differ. Login has a separate fixed limit of 60 requests/minute per account. Rate limits count HTTP requests, not API units.
Pricing: No subscription or credit card is required to start. PAYG top-ups can be bought at any time and are used after a plan allowance runs out; plans and top-ups accept card or cryptocurrency. Plans, PAYG packs, and per-endpoint unit costs: https://tweetapi.com/pricing.json
Usage: Trial, subscription, and PAYG allowances are API units, not returned posts. Most billable requests cost 1 unit; /tw-v2/xchat/send costs 10 and /tw-v2/auth/login costs 50. GET /tw-v2/account/usage is free and returns the remaining allowance and PAYG balance. An additional page or retry is another request and can consume units. See https://tweetapi.com/pricing and https://tweetapi.com/docs/getting-started/overview#plan-limits.
Billing: A unit cost applies when a request is billable. Metered HTTP 200-499 responses generally bill except 400, 401, 403, 409, 422, and 429; 5xx do not bill. A 404 for a path or method that doesn't exist does not bill. The follow-request list, accept, and deny operations bill only valid successes. An aborted or timed-out action can have an uncertain outcome; check before retrying. Available plan allowance is used before valid PAYG balance. See https://tweetapi.com/terms#payg for wallet terms.
Errors: Errors from /tw-v2 routes are JSON with statusCode, message, and, when one applies, a stable code; new codes may be added. A 429 from plan limits has code RATE_LIMITED (requests per second, writes per minute, or requests in progress; wait for its Retry-After seconds), QUOTA_EXHAUSTED (allowance and PAYG balance used up), or SUBSCRIPTION_INACTIVE (subscription expired or inactive); do not retry the last two. A 429 without a code is temporary; use bounded backoff. Other codes: ACCOUNT_SUSPENDED and ACCOUNT_LOCKED (the X account behind an action can no longer be used), PROXY_ERROR (502) and PROXY_TIMEOUT (504), and the login outcomes INVALID_CREDENTIALS, TWO_FACTOR_REQUIRED, INVALID_TWO_FACTOR_CODE, EMAIL_VERIFICATION_REQUIRED, and LOGIN_RUNTIME_UNAVAILABLE. Responses do not include X-RateLimit-* headers. A 503 may include Retry-After; follow it when present and use bounded retries.

================================================
AUTHENTICATION
================================================

All API requests require an API key in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://api.tweetapi.com/tw-v2/[endpoint]

Operations acting on an X account may require authToken (the account's auth_token cookie value). Login uses username and password instead. Some account operations require a proxy; check each operation's required fields. Keep all credentials on your server.

================================================
SHARED TWEET OBJECT NOTES
================================================

Endpoints that return normalized Tweet objects may include `reactionContext`.
Reaction posts are returned as quote tweets (`type: "quote"`) with `reactionContext.isReaction === true`.
Normal tweets and normal quote tweets return `reactionContext: null`.

Shape:
{
  "reactionContext": {
    "isReaction": true,
    "targetTweetId": "2000000000000000001",
    "targetTweetUrl": "https://x.com/sample_user_00001/status/2000000000000000001",
    "targetAuthor": {
      "id": "1000000000000000001",
      "username": "sample_user_00001",
      "name": "Sample User 00001",
      "avatar": "https://example.com/images/sample-avatar-00001.jpg",
      "isBlueVerified": true
    }
  }
}

If a reaction tweet has no target details, `targetTweetId`, `targetTweetUrl`, and `targetAuthor` may be null.

================================================
ENDPOINTS BY CATEGORY
================================================

USER: 21 endpoints
TWEET: 5 endpoints
POST: 6 endpoints
INTERACTION: 15 endpoints
LIST: 7 endpoints
PROFILE: 6 endpoints
COMMUNITY: 12 endpoints
SPACE: 2 endpoints
SEARCH: 1 endpoints
TRENDS: 2 endpoints
AUTH: 1 endpoints
X CHAT (Encrypted DMs): 5 endpoints
UNENCRYPTED DM (Legacy): 8 endpoints
ACCOUNT: 1 endpoints

================================================
DETAILED ENDPOINT DOCUMENTATION
================================================


================================================================================
USER ENDPOINTS
================================================================================

### GET /tw-v2/user/by-username

**Description:**
Retrieve comprehensive user profile information using a Twitter username. Returns detailed user data including statistics, verification status, and profile metadata.

**Endpoint guide:** https://tweetapi.com/docs/user/by-username
**Usage cost:** 1 API unit per billable request

**Parameters:**
- username (string, required): Twitter username without @ symbol (e.g., 'sample_user_96991')

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/by-username?username=sample_user_96991" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/by-usernames

**Description:**
Retrieve comprehensive user profile information for multiple users in a single request using their Twitter usernames. Returns detailed user data including statistics, verification status, and profile metadata for up to 100 users at once.

**Endpoint guide:** https://tweetapi.com/docs/user/by-usernames
**Usage cost:** 1 API unit per billable request

**Parameters:**
- usernames (string, required): Comma-separated list of Twitter usernames without @ symbol (maximum 100 usernames per request). The @ symbol is automatically stripped if provided.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/by-usernames?usernames=sample_user_96991,sample_user_59576,sample_user_11511" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/by-id

**Description:**
Retrieve comprehensive user profile information using a Twitter user ID. Returns detailed user data including statistics, verification status, and profile metadata.

**Endpoint guide:** https://tweetapi.com/docs/user/by-user-id
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/by-id?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/by-ids

**Description:**
Retrieve comprehensive user profile information for multiple users in a single request using their Twitter user IDs. Returns detailed user data including statistics, verification status, and profile metadata for up to 100 users at once.

**Endpoint guide:** https://tweetapi.com/docs/user/by-user-ids
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userIds (string, required): Comma-separated list of Twitter user IDs to retrieve (maximum 100 IDs per request).

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/by-ids?userIds=10017528,123456789" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/tweets

**Description:**
Retrieve tweets posted by a specific user. Returns a paginated timeline of original tweets (no replies).

**Endpoint guide:** https://tweetapi.com/docs/user/tweets
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/tweets?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/tweets-and-replies

**Description:**
Retrieve tweets and replies posted by a specific user. Returns a paginated timeline including both original tweets and replies.

**Endpoint guide:** https://tweetapi.com/docs/user/tweets-and-replies
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/tweets-and-replies?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/photos

**Description:**
Retrieve a user's posts that contain photos, as shown on the Photos tab of their profile. Returns a paginated timeline of posts.

**Usage notes:**

This is X's Photos tab only. Videos are a separate feed (`/tw-v2/user/videos`); there is no combined media feed or GIF filter. Pages can be shorter than 20 posts, and a short page does not mean the end: keep passing `nextCursor` until it is `null`.

**Endpoint guide:** https://tweetapi.com/docs/user/photos
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/photos?userId=10017528" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/videos

**Description:**
Retrieve a user's posts that contain videos, as shown on the Videos tab of their profile. Returns a paginated timeline of posts.

**Usage notes:**

This is X's Videos tab only. Photos are a separate feed (`/tw-v2/user/photos`). A short page does not mean the end: keep passing `nextCursor` until it is `null`.

**Endpoint guide:** https://tweetapi.com/docs/user/videos
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/videos?userId=10017528" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/lists

**Description:**
Retrieve the Lists shown on a user's Lists tab, in the order X shows them. Returns a paginated list of Lists.

**Usage notes:**

These are the Lists X shows on the profile's Lists tab. They are not only Lists the user created: X can include Lists owned by other accounts, so check `owner` on each List. Every List X returns is included, Private ones too, and `mode` says which. For the Lists other accounts added this user to, use `/tw-v2/user/list-memberships`; for the users in one List, use `/tw-v2/list/members`. A page can be short or even empty without being the last one: keep passing `nextCursor` until it is `null`. A user with no Lists returns an empty list.

**Endpoint guide:** https://tweetapi.com/docs/user/lists
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/lists?userId=10017528" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/list-memberships

**Description:**
Retrieve the Lists a user has been added to as a member, in the order X shows them. Returns a paginated list of Lists.

**Usage notes:**

These are the Lists that include the user as a member, as on x.com's "Member of" view. They can be owned by any account, so check `owner` on each List. Every List X returns is included, Private ones too, and `mode` says which. For the Lists on the user's own Lists tab, use `/tw-v2/user/lists`; for the users in one List, use `/tw-v2/list/members`. A page can be short or even empty without being the last one: keep passing `nextCursor` until it is `null`. A user who is in no Lists returns an empty list.

**Endpoint guide:** https://tweetapi.com/docs/user/list-memberships
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/list-memberships?userId=10017528" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/following

**Description:**
Get a paginated list of users that the specified account is following. X sets the page size; to choose it with `count`, use `/tw-v2/user/following-list`. Returns user objects with complete profile information.

**Endpoint guide:** https://tweetapi.com/docs/user/following-v2
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/following?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/followers

**Description:**
Get a paginated list of users following the specified account. X sets the page size; to choose it with `count`, use `/tw-v2/user/followers-list`. Returns user objects with complete profile information.

**Endpoint guide:** https://tweetapi.com/docs/user/followers-v2
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/followers?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/verified-followers

**Description:**
Get a paginated list of the specified account's followers that have a verified (blue check) badge. Returns user objects with complete profile information.

**Endpoint guide:** https://tweetapi.com/docs/user/verified-followers
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/verified-followers?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/subscriptions

**Description:**
Get a paginated list of the creator accounts that the specified user subscribes to through X Subscriptions (formerly Super Follows). Returns user objects with complete profile information.

**Endpoint guide:** https://tweetapi.com/docs/user/subscriptions
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/subscriptions?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/following-list

**Description:**
Get a paginated list of users that the specified account is following, with the page size set by `count` (default 20). Returns user objects with complete profile information. `/tw-v2/user/following` returns the same accounts with a page size chosen by X.

**Endpoint guide:** https://tweetapi.com/docs/user/following-v1
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- count (string, optional): Numeric result count string (default: 20; no explicit backend maximum)
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/following-list?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/followers-list

**Description:**
Get a paginated list of users following the specified account, with the page size set by `count` (default 20). Returns user objects with complete profile information. `/tw-v2/user/followers` returns the same followers with a page size chosen by X.

**Endpoint guide:** https://tweetapi.com/docs/user/followers-v1
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- count (string, optional): Numeric result count string (default: 20; no explicit backend maximum)
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/followers-list?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/following-ids

**Description:**
Get a paginated list of user IDs that the specified account follows. Returns string IDs in data and next and previous cursors in pagination.

**Endpoint guide:** https://tweetapi.com/docs/user/following-ids
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- count (string, optional): Numeric result count string (default: 20; no explicit backend maximum)
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/following-ids?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/followers-ids

**Description:**
Get a paginated list of the specified account's follower IDs. Returns string IDs in data and next and previous cursors in pagination.

**Endpoint guide:** https://tweetapi.com/docs/user/followers-ids
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- count (string, optional): Numeric result count string (default: 20; no explicit backend maximum)
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/followers-ids?userId=10093010" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/friendship

**Description:**
Check if a follow relationship exists between two users.

**Endpoint guide:** https://tweetapi.com/docs/user/check-follow
**Usage cost:** 1 API unit per billable request

**Parameters:**
- subjectId (string, required): The user ID of the subject user (the follower)
- targetId (string, required): The user ID of the target user (the one being followed)

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/friendship?subjectId=10017528&targetId=123456789" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/about-account

**Description:**
Retrieve detailed account information for a user including location, verification details, username history, affiliate relationships, and account creation source.

**Endpoint guide:** https://tweetapi.com/docs/user/about-account
**Usage cost:** 1 API unit per billable request

**Parameters:**
- username (string, required): Twitter username without @ symbol (e.g., 'sample_user_96991')

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/about-account?username=sample_user_96991" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/user/affiliates

**Description:**
Retrieve the accounts affiliated with a business profile, as shown on its Affiliates tab. Returns a paginated list of users.

**Usage notes:**

Returns X's default affiliate group. Named business teams are not supported. A profile with no affiliates returns an empty list. A short page does not mean the end: keep passing `nextCursor` until it is `null`.

**Endpoint guide:** https://tweetapi.com/docs/user/affiliates
**Usage cost:** 1 API unit per billable request

**Parameters:**
- userId (string, required): Unique Twitter user ID (e.g., '10017528')
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/user/affiliates?userId=10017528" \
  -H "X-API-Key: YOUR_API_KEY"
```


================================================================================
TWEET ENDPOINTS
================================================================================

### GET /tw-v2/tweet/details

**Description:**
Get detailed information about a specific tweet including full metadata, engagement metrics, attached X Article content, its parent tweets (`ancestors`, oldest first) when it is a reply, and a page of replies.

**Endpoint guide:** https://tweetapi.com/docs/tweet/details--conversation
**Usage cost:** 1 API unit per billable request

**Parameters:**
- tweetId (string, required): Unique tweet/post ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.
- sortBy (string, optional): Sort order for conversation replies (Relevance, Recency, Likes). Default: Relevance

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/tweet/details?tweetId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/tweet/details-by-ids

**Description:**
Retrieve detailed information for multiple tweets in a single request. Returns comprehensive tweet data including author information, engagement metrics, media attachments, and metadata for up to 200 tweets at once.

**Endpoint guide:** https://tweetapi.com/docs/tweet/details-by-ids
**Usage cost:** 1 API unit per billable request

**Parameters:**
- ids (string, required): Comma-separated list of tweet IDs to retrieve (maximum 200 IDs per request)

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/tweet/details-by-ids?ids=2002171750977445519,2001085712943977436,2001390983706415851" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/tweet/retweets

**Description:**
Retrieve users who retweeted a specific tweet. Returns a paginated list of retweets with user information.

**Endpoint guide:** https://tweetapi.com/docs/tweet/retweets
**Usage cost:** 1 API unit per billable request

**Parameters:**
- tweetId (string, required): Unique tweet/post ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/tweet/retweets?tweetId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/tweet/quotes

**Description:**
Retrieve quote tweets for a specific tweet. Returns tweets that quote the original tweet with additional commentary.

**Endpoint guide:** https://tweetapi.com/docs/tweet/quotes
**Usage cost:** 1 API unit per billable request

**Parameters:**
- tweetId (string, required): Unique tweet/post ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/tweet/quotes?tweetId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### POST /tw-v2/tweet/translate

**Description:**
Translate tweet text to a target language using the built-in translation service.

**Endpoint guide:** https://tweetapi.com/docs/tweet/translate
**Usage cost:** 1 API unit per billable request

**Request Body:**
- tweetId (string, required): The ID of the tweet to translate
- dstLang (string, required): Target language code (e.g., "en", "es", "fr", "de", "ja", "zh-CN")

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/tweet/translate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tweetId": "1234567890",
  "dstLang": "es"
}'
```


================================================================================
POST ENDPOINTS
================================================================================

### POST /tw-v2/interaction/create-post

**Description:**
Post a new tweet to the platform. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/post/create-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the tweet (max 280 characters for non-premium, 25,000 for premium)
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)
- replyOption (object, optional): Optional reply controls. Use {"mode":"everyone"}, {"mode":"accounts_you_follow"}, {"mode":"accounts_you_follow_and_followed"}, {"mode":"mentioned_accounts"}, {"mode":"verified_accounts"}, or {"mode":"regions","regions":["NAM","EUR"]}. Region buckets: NAM, EAS, AFR, SEA, SAM, EUR, AUS, SAS, WES, CAS.

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "text": "Hello, world!",
  "replyOption": {"mode":"mentioned_accounts"}
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/create-post-quote

**Description:**
Quote tweet another tweet with your own commentary. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/post/create-post-quote
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the quote tweet (max 280 characters for non-premium, 25,000 for premium)
- attachmentUrl (string, required): The URL of the tweet to quote (e.g. https://x.com/sample_user_00001/status/2001844185)
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)
- replyOption (object, optional): Optional reply controls. Use {"mode":"everyone"}, {"mode":"accounts_you_follow"}, {"mode":"accounts_you_follow_and_followed"}, {"mode":"mentioned_accounts"}, {"mode":"verified_accounts"}, or {"mode":"regions","regions":["NAM","EUR"]}. Region buckets: NAM, EAS, AFR, SEA, SAM, EUR, AUS, SAS, WES, CAS.

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-post-quote" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "text": "Hello, world!",
  "attachmentUrl": "https://x.com/sample_user_00001/status/2001844185",
  "replyOption": {"mode":"regions","regions":["NAM","EUR"]}
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/create-post-with-media

**Description:**
Post a new tweet with media attachments to the platform. Supports text content up to 280 characters for non-premium users (or 25,000 for premium users) and up to 4 images or 1 video.

**Endpoint guide:** https://tweetapi.com/docs/post/create-post-with-media
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the tweet (max 280 characters for non-premium, 25,000 for premium)
- media (array, required): Array of media objects (1-4 items). Each object must use exactly one source: {url: string}, {data: string, type: string}, or {media_id: string}. media_id must be a digit-only Twitter media_id_string uploaded and finalized with the same account.
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)
- replyOption (object, optional): Optional reply controls. Use {"mode":"everyone"}, {"mode":"accounts_you_follow"}, {"mode":"accounts_you_follow_and_followed"}, {"mode":"mentioned_accounts"}, {"mode":"verified_accounts"}, or {"mode":"regions","regions":["NAM","EUR"]}. Region buckets: NAM, EAS, AFR, SEA, SAM, EUR, AUS, SAS, WES, CAS.

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-post-with-media" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "text": "Hello, world!",
  "media": [{"url":"https://example.com/link-94089/profile-29900/image.jpg"}],
  "replyOption": {"mode":"verified_accounts"}
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/reply-post

**Description:**
Reply to an existing tweet. Creates a tweet in the conversation thread. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/post/reply-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the reply (max 280 characters for non-premium, 25,000 for premium)
- tweetId (string, required): The ID of the tweet to reply to
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/reply-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "text": "Hello, world!",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/reply-post-with-media

**Description:**
Reply to an existing tweet with media attachments. Creates a tweet in the conversation thread with up to 4 images or 1 video. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/post/reply-post-with-media
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the reply (max 280 characters for non-premium, 25,000 for premium)
- tweetId (string, required): The ID of the tweet to reply to
- media (array, required): Array of media objects (1-4 items). Each object must use exactly one source: {url: string}, {data: string, type: string}, or {media_id: string}. media_id must be a digit-only Twitter media_id_string uploaded and finalized with the same account.
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/reply-post-with-media" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "text": "Hello, world!",
  "tweetId": "1234567890",
  "media": [{"url":"https://example.com/link-94089/profile-29900/image.jpg"}]
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/delete-post

**Description:**
Delete a tweet posted by the authenticated user.

**Endpoint guide:** https://tweetapi.com/docs/post/delete-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the tweet to delete
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/delete-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```


================================================================================
INTERACTION ENDPOINTS
================================================================================

### POST /tw-v2/interaction/like-post

**Description:**
Like a tweet on behalf of an authenticated user.

**Endpoint guide:** https://tweetapi.com/docs/interaction/favorite-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the tweet to favorite
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/like-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/unlike-post

**Description:**
Unlike a tweet on behalf of an authenticated user.

**Endpoint guide:** https://tweetapi.com/docs/interaction/unfavorite-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the tweet to unfavorite
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/unlike-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/retweet

**Description:**
Retweet a tweet on behalf of an authenticated user. This endpoint allows you to programmatically retweet any public tweet using the user's authentication token.

**Endpoint guide:** https://tweetapi.com/docs/interaction/retweet
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the tweet to retweet
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/retweet" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/delete-retweet

**Description:**
Remove a retweet (unretweet) on behalf of an authenticated user. This endpoint allows you to programmatically undo a retweet using the user's authentication token.

**Endpoint guide:** https://tweetapi.com/docs/interaction/delete-retweet
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the original tweet that was retweeted
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/delete-retweet" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/bookmark

**Description:**
Add a tweet to your bookmarks for later viewing.

**Endpoint guide:** https://tweetapi.com/docs/interaction/bookmark
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the tweet to bookmark
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/bookmark" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/delete-bookmark

**Description:**
Remove a tweet from your bookmarks.

**Endpoint guide:** https://tweetapi.com/docs/interaction/delete-bookmark
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- tweetId (string, required): The ID of the tweet to remove from bookmarks
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/delete-bookmark" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "tweetId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/bookmarks

**Description:**
Retrieve the posts bookmarked by the X account behind authToken. Returns a paginated timeline of posts.

**Usage notes:**

Returns bookmarks of the authToken account only; there is no way to read another user's bookmarks. Bookmarked posts that X no longer returns are left out, so a page can hold fewer than 20 posts. Keep passing `nextCursor` until it is `null`. Bookmark folders and bookmark search are not supported.

**Endpoint guide:** https://tweetapi.com/docs/interaction/bookmarks
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Authentication token (auth_token cookie value) of the X account whose data you read. Only that account's data is returned.
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/bookmarks?authToken=YOUR_AUTH_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/likes

**Description:**
Retrieve the posts liked by the X account behind authToken. Returns a paginated timeline of posts.

**Usage notes:**

Supply both `authToken` and the numeric `userId` of that same X account. The user ID is not looked up automatically; use `/tw-v2/user/by-username` if you only know the username. This endpoint is for your own account's likes. Supplying another account's ID does not grant access to its private likes. Keep the same account and pass `nextCursor` until it is `null`.

**Endpoint guide:** https://tweetapi.com/docs/interaction/likes
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Authentication token (auth_token cookie value) of the same X account identified by userId.
- userId (string, required): Numeric user ID of the X account that authToken belongs to. Required; the ID is not looked up automatically.
- cursor (string, optional): Pagination cursor from the previous response's nextCursor. Omit for the first page.
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/likes?authToken=YOUR_AUTH_TOKEN&userId=1000000000000000001" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/follow

**Description:**
Follow a user account.

**Endpoint guide:** https://tweetapi.com/docs/interaction/follow
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- userId (string, required): The numeric user ID of the account to follow
- username (string, optional): Optional username of the target account
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/follow" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "userId": "10017528"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/unfollow

**Description:**
Unfollow a user account.

**Endpoint guide:** https://tweetapi.com/docs/interaction/unfollow
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- userId (string, required): The numeric user ID of the account to unfollow
- username (string, optional): Optional username of the target account
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/unfollow" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "userId": "10017528"
}'
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/follow-requests

**Description:**
Retrieve pending follow-request user IDs for the authenticated X account.

**Usage notes:**

A successful request costs one API unit; failed requests are not billed.

**Endpoint guide:** https://tweetapi.com/docs/interaction/follow-requests
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Authentication token (auth_token cookie value) for the X account whose incoming requests you manage
- cursor (string, optional): Pagination cursor as a string; default "-1" for the first page
- count (number, optional): Page size as an integer from 1 to 100; default 100
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/follow-requests?authToken=YOUR_AUTH_TOKEN&cursor=-1&count=100" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/accept-follow-request

**Description:**
Accept a pending follow request for the authenticated X account.

**Usage notes:**

A successful request costs one API unit; failed requests are not billed. Do not retry automatically. If a timeout leaves the outcome uncertain, check the account in X before retrying manually.

**Endpoint guide:** https://tweetapi.com/docs/interaction/accept-follow-request
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Authentication token (auth_token cookie value) for the X account whose incoming requests you manage
- userId (string, required): Requesting user ID as a digit-only string; preserve all digits
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/accept-follow-request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "userId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/deny-follow-request

**Description:**
Deny a pending follow request for the authenticated X account.

**Usage notes:**

A successful request costs one API unit; failed requests are not billed. Do not retry automatically. If a timeout leaves the outcome uncertain, check the account in X before retrying manually.

**Endpoint guide:** https://tweetapi.com/docs/interaction/deny-follow-request
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Authentication token (auth_token cookie value) for the X account whose incoming requests you manage
- userId (string, required): Requesting user ID as a digit-only string; preserve all digits
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/deny-follow-request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "userId": "1234567890"
}'
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/notifications

**Description:**
Retrieve the authenticated user's notifications timeline on the platform. Returns notifications including likes, retweets, mentions, and follows.

**Endpoint guide:** https://tweetapi.com/docs/interaction/notifications
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- timelineType (string, optional): Type of notifications to retrieve: 'All', 'Verified', or 'Mentions' (default: 'All')
- count (number, optional): Number of results to return per page (min: 1, max: 100, default: 20)
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/notifications?authToken=YOUR_AUTH_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/user-analytics

**Description:**
Get analytics for the X account identified by the required authToken, including account engagement and follower metrics.

**Endpoint guide:** https://tweetapi.com/docs/interaction/user-analytics
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Authentication token (auth_token cookie value) for the account whose analytics are returned
- toTime (string, optional): End time for analytics period in ISO 8601 format (default: current time)
- fromTime (string, optional): Start time for analytics period in ISO 8601 format (default: 30 days ago)
- granularity (string, optional): Time granularity for metrics: Daily, Weekly, or Monthly (default: Daily)
- showVerifiedFollowers (boolean, optional): Include verified follower metrics (default: true)
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/user-analytics?authToken=YOUR_AUTH_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"
```


================================================================================
LIST ENDPOINTS
================================================================================

### GET /tw-v2/list/details

**Description:**
Get detailed information about a specific list including metadata, member count, and configuration settings.

**Endpoint guide:** https://tweetapi.com/docs/list/details
**Usage cost:** 1 API unit per billable request

**Parameters:**
- listId (string, required): Unique list ID

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/list/details?listId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/list/tweets

**Description:**
Retrieve tweets from a specific list. Returns a paginated timeline of tweets posted by list members.

**Endpoint guide:** https://tweetapi.com/docs/list/tweets
**Usage cost:** 1 API unit per billable request

**Parameters:**
- listId (string, required): Unique list ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/list/tweets?listId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/list/members

**Description:**
Get a paginated list of members in a list.

**Endpoint guide:** https://tweetapi.com/docs/list/members
**Usage cost:** 1 API unit per billable request

**Parameters:**
- listId (string, required): Unique list ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/list/members?listId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/list/followers

**Description:**
Get a paginated list of users following a specific list. Returns user objects with complete profile information.

**Endpoint guide:** https://tweetapi.com/docs/list/followers
**Usage cost:** 1 API unit per billable request

**Parameters:**
- listId (string, required): Unique list ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/list/followers?listId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### POST /tw-v2/list/create

**Description:**
Create a list for the authenticated Twitter/X account.

**Endpoint guide:** https://tweetapi.com/docs/list/create
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- name (string, required): List name, up to 25 characters
- description (string, optional): Optional list description, up to 100 characters. Defaults to an empty string.
- isPrivate (boolean, optional): Whether the list should be private. Defaults to true.

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/list/create" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "name": "Market Watch",
  "description": "Accounts to monitor for market updates",
  "isPrivate": true
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/list/add-member

**Description:**
Add a user to one of the authenticated account's lists.

**Endpoint guide:** https://tweetapi.com/docs/list/add-member
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- listId (string, required): The ID of the list to add the user to
- userId (string, required): The ID of the user to add to the list
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/list/add-member" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "listId": "1234567890",
  "userId": "10017528"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/list/remove-member

**Description:**
Remove a user from one of the authenticated account's lists.

**Endpoint guide:** https://tweetapi.com/docs/list/remove-member
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- listId (string, required): The ID of the list to remove the user from
- userId (string, required): The ID of the user to remove from the list
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/list/remove-member" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "listId": "1234567890",
  "userId": "10017528"
}'
```


================================================================================
PROFILE ENDPOINTS
================================================================================

### POST /tw-v2/profile/update

**Description:**
Update display profile fields for the authenticated Twitter/X account.

**Endpoint guide:** https://tweetapi.com/docs/profile/update
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- name (string, optional): Display name, up to 50 characters
- bio (string, optional): Profile bio, up to 160 characters
- location (string, optional): Profile location, up to 30 characters
- website (string, optional): Profile website URL. Use an empty string to clear the website.
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/profile/update" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "name": "Sample User",
  "bio": "Building with TweetAPI",
  "location": "Bangkok",
  "website": "https://example.com"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/profile/username

**Description:**
Change the username for the authenticated X account. The username must contain 5-15 ASCII letters, numbers, or underscores and must not include @. A successful response costs one API unit. This operation has no idempotency guarantee. A 502 response can be transient, but if the outcome is unclear, check the account's current username before retrying. After a successful change, the old username becomes immediately available for another account to claim.

**Endpoint guide:** https://tweetapi.com/docs/profile/username
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- password (string, required): Password for the authenticated X account
- username (string, required): Desired username, using 5-15 ASCII letters, numbers, or underscores without @
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/profile/username" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "password": "YOUR_PASSWORD",
  "username": "sample_user"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/profile/avatar

**Description:**
Update the profile picture for the authenticated Twitter/X account using an image URL or base64 image payload.

**Endpoint guide:** https://tweetapi.com/docs/profile/avatar
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- media (object, required): Image object. Use {url:string} or {data:string,type:string}. Supported types are image/jpeg, image/jpg, image/png, and image/webp. Direct media_id values are not supported.
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/profile/avatar" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "media": {"url":"https://example.com/images/profile-avatar.jpg"}
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/profile/banner

**Description:**
Update the profile banner for the authenticated Twitter/X account using an image URL or base64 image payload.

**Endpoint guide:** https://tweetapi.com/docs/profile/banner
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- media (object, required): Image object. Use {url:string} or {data:string,type:string}. Supported types are image/jpeg, image/jpg, image/png, and image/webp. Direct media_id values are not supported.
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/profile/banner" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "media": {"url":"https://example.com/images/profile-banner.jpg"}
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/profile/remove-banner

**Description:**
Remove the profile banner from the authenticated X account.

**Endpoint guide:** https://tweetapi.com/docs/profile/remove-banner
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/profile/remove-banner" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/profile/privacy

**Description:**
Change the authenticated X account between public and private.

**Endpoint guide:** https://tweetapi.com/docs/profile/privacy
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- isPrivate (boolean, required): Set to true for a private account or false for a public account
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/profile/privacy" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "isPrivate": true
}'
```


================================================================================
COMMUNITY ENDPOINTS
================================================================================

### GET /tw-v2/community/details

**Description:**
Get detailed information about a specific community including metadata, member count, and settings.

**Endpoint guide:** https://tweetapi.com/docs/community/details
**Usage cost:** 1 API unit per billable request

**Parameters:**
- communityId (string, required): Unique community ID

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/community/details?communityId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/community/tweets

**Description:**
Retrieve tweets from a specific community. Returns a paginated timeline of community tweets with configurable sorting.

**Endpoint guide:** https://tweetapi.com/docs/community/tweets
**Usage cost:** 1 API unit per billable request

**Parameters:**
- communityId (string, required): Unique community ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.
- sortBy (string, optional): Optional sort order for results (Relevance, Recency). Defaults to Relevance.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/community/tweets?communityId=1234567890&sortBy=Relevance" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/community/members

**Description:**
Get a paginated list of members in a community.

**Endpoint guide:** https://tweetapi.com/docs/community/members
**Usage cost:** 1 API unit per billable request

**Parameters:**
- communityId (string, required): Unique community ID
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/community/members?communityId=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/community/search

**Description:**
Search for communities by keyword. Returns a list of communities matching the search query with basic information like name, member count, and topic.

**Endpoint guide:** https://tweetapi.com/docs/community/search
**Usage cost:** 1 API unit per billable request

**Parameters:**
- query (string, required): Search query string to find communities
- cursor (string, optional): Pagination cursor for fetching next page of results

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/community/search?query=programming" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/create-community-post

**Description:**
Post a new tweet to a specific community. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/community/create-community-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the tweet (max 280 characters for non-premium, 25,000 for premium)
- communityId (string, required): The ID of the community to post to (numeric only)
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-community-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "text": "Sample post text 40338 for documentation.",
  "communityId": "1234567890",
  "proxy": "proxy.example.com:8080@user:pass"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/create-community-post-with-media

**Description:**
Post a new tweet with media attachments to a specific community. Supports text content up to 280 characters for non-premium users (or 25,000 for premium users) and up to 4 images or 1 video.

**Endpoint guide:** https://tweetapi.com/docs/community/create-community-post-with-media
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the tweet (max 280 characters for non-premium, 25,000 for premium)
- communityId (string, required): The ID of the community to post to (numeric only)
- media (array, required): Array of media objects (1-4 items). Each object must use exactly one source: {url: string}, {data: string, type: string}, or {media_id: string}. media_id must be a digit-only Twitter media_id_string uploaded and finalized with the same account.
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-community-post-with-media" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "text": "Sample post text 87088 for documentation.",
  "communityId": "1234567890",
  "media": [{"url":"https://example.com/link-94089/profile-29900/image.jpg"}],
  "proxy": "proxy.example.com:8080@user:pass"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/reply-community-post

**Description:**
Reply to an existing tweet within a community. Creates a reply in the conversation thread with community context. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/community/reply-community-post
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the reply (max 280 characters for non-premium, 25,000 for premium)
- tweetId (string, required): The ID of the tweet to reply to (numeric only)
- communityId (string, required): The ID of the community to post to (numeric only)
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/reply-community-post" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "text": "Sample post text 67773 for documentation.",
  "tweetId": "1234567890",
  "communityId": "9876543210",
  "proxy": "proxy.example.com:8080@user:pass"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/reply-community-post-with-media

**Description:**
Reply to an existing tweet within a community with media attachments. Creates a reply in the conversation thread with community context and up to 4 images or 1 video. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/community/reply-community-post-with-media
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the reply (max 280 characters for non-premium, 25,000 for premium)
- tweetId (string, required): The ID of the tweet to reply to (numeric only)
- communityId (string, required): The ID of the community to post to (numeric only)
- media (array, required): Array of media objects (1-4 items). Each object must use exactly one source: {url: string}, {data: string, type: string}, or {media_id: string}. media_id must be a digit-only Twitter media_id_string uploaded and finalized with the same account.
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/reply-community-post-with-media" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "text": "Sample post text 77733 for documentation.",
  "tweetId": "1234567890",
  "communityId": "9876543210",
  "media": [{"url":"https://example.com/link-94089/profile-29900/image.jpg"}],
  "proxy": "proxy.example.com:8080@user:pass"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/create-community-quote

**Description:**
Quote tweet another tweet inside a specific community with your own commentary. Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/community/create-community-quote
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the quote tweet (max 280 characters for non-premium, 25,000 for premium)
- attachmentUrl (string, required): The URL of the tweet to quote (e.g. https://x.com/sample_user_00001/status/2001844185)
- communityId (string, required): The ID of the community to post to (numeric only)
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-community-quote" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "text": "Sample post text 93445 for documentation.",
  "attachmentUrl": "https://x.com/sample_user_00001/status/2001844185",
  "communityId": "4001272782786434945",
  "proxy": "proxy.example.com:8080@user:pass"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/create-community-quote-with-media

**Description:**
Quote tweet another tweet inside a specific community with your own commentary and media attachments (images or video). Supports text content up to 280 characters for non-premium users, or 25,000 characters for premium users.

**Endpoint guide:** https://tweetapi.com/docs/community/create-community-quote-with-media
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- text (string, required): The text content of the quote tweet (max 280 characters for non-premium, 25,000 for premium)
- attachmentUrl (string, required): The URL of the tweet to quote (e.g. https://x.com/sample_user_00001/status/2001844185)
- communityId (string, required): The ID of the community to post to (numeric only)
- media (array, required): Array of media objects (1-4 items). Each object must use exactly one source: {url: string}, {data: string, type: string}, or {media_id: string}. media_id must be a digit-only Twitter media_id_string uploaded and finalized with the same account.
- proxy (string, required): Proxy in format 'hostname:port@username:password'
- disableLinkPreview (boolean, optional): When true, disables link preview cards for tweets containing URLs (defaults to false)

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/create-community-quote-with-media" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "text": "Sample post text 93445 for documentation.",
  "attachmentUrl": "https://x.com/sample_user_00001/status/2001844185",
  "communityId": "4001272782786434945",
  "media": [{"url": "https://example.com/link-94089/profile-29900/image.jpg"}],
  "proxy": "proxy.example.com:8080@user:pass"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/join-community

**Description:**
Join a community. Returns community details including name, description, member count, and your role after joining.

**Endpoint guide:** https://tweetapi.com/docs/community/join-community
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- communityId (string, required): The numeric ID of the community to join
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/join-community" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "communityId": "1001937475184068444"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/leave-community

**Description:**
Leave a community. Returns community details including name, description, and member count after leaving.

**Endpoint guide:** https://tweetapi.com/docs/community/leave-community
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- communityId (string, required): The numeric ID of the community to leave
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/leave-community" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "communityId": "1001937475184068444"
}'
```


================================================================================
SPACE ENDPOINTS
================================================================================

### GET /tw-v2/space/by-id

**Description:**
Retrieve detailed information about a platform Space (audio room) by its ID. Returns comprehensive data including title, state, creator, participants, topics, and engagement stats.

**Endpoint guide:** https://tweetapi.com/docs/space/by-id
**Usage cost:** 1 API unit per billable request

**Parameters:**
- spaceId (string, required): Unique Space ID (e.g., '1MnxnPmLRQBGO')

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/space/by-id?spaceId=1MnxnPmLRQBGO" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/space/stream-url

**Description:**
Get the audio stream URL for a platform Space. Returns an HLS stream URL that can be used to listen to the Space audio. The mediaKey can be obtained from the Space details endpoint.

**Endpoint guide:** https://tweetapi.com/docs/space/stream-url
**Usage cost:** 1 API unit per billable request

**Parameters:**
- mediaKey (string, required): Media key of the Space (obtained from the space by-id endpoint's mediaKey field)

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/space/stream-url?mediaKey=28_1991353658102149130" \
  -H "X-API-Key: YOUR_API_KEY"
```


================================================================================
SEARCH ENDPOINTS
================================================================================

### GET /tw-v2/search

**Description:**
Search posts or people with the same query syntax and advanced operators as X search. `Latest`, `Photos`, and `Videos` return posts in `data`; `People` returns users; `Top` returns items with `type` and `content` fields.

**Endpoint guide:** https://tweetapi.com/docs/explore/search
**Usage cost:** 1 API unit per billable request

**Parameters:**
- query (string, required): Search query string, 1-512 characters. Supports advanced search operators.
- type (string, required): Type of search results (Latest, Top, People, Photos, Videos)
- cursor (string, optional): Pagination cursor for fetching next page of results. Obtained from previous response.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/search?query=javascript&type=Latest" \
  -H "X-API-Key: YOUR_API_KEY"
```


================================================================================
TRENDS ENDPOINTS
================================================================================

### GET /tw-v2/trends

**Description:**
Retrieve the trending topics X shows worldwide, in a supported country, or at a location identified by its WOEID (Where On Earth ID).

**Usage notes:**

Use `country=US` for the United States or `country=IT` for Italy. Country codes are two letters and case-insensitive. Omit both `country` and `woeid` for worldwide trends. Alternatively, use `woeid=1` for worldwide or a supported country or city WOEID from `/tw-v2/trends/locations`. Supply only one location parameter; sending both returns 400. Not every country is supported, and an unsupported country code returns 404 instead of falling back to worldwide. If the country list is unavailable or invalid, the request returns 502 and is not billed. The response names the location X answered for. Trends are in X's order. `tweetVolume` is `null` when X does not report a volume, which is usually the case; do not read rank as volume. When X has no trends for a WOEID, TweetAPI checks X's location list: a 404 means the list confirmed the WOEID is not supported. If that can't be confirmed, for example because the list is unavailable or still includes the WOEID, the request returns 502 and is not billed. The response is not paginated.

**Endpoint guide:** https://tweetapi.com/docs/trends/by-location
**Usage cost:** 1 API unit per billable request

**Parameters:**
- country (string, optional): Two-letter country code, such as US or IT (case-insensitive). Cannot be combined with woeid. Omit both for worldwide trends.
- woeid (string, optional): Yahoo Where On Earth ID for a country or city, or 1 for worldwide. Get supported IDs from /tw-v2/trends/locations. Cannot be combined with country. Omit both for worldwide trends.

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/trends?country=US" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/trends/locations

**Description:**
List the locations X serves trends for, with the WOEID to pass to /tw-v2/trends.

**Usage notes:**

The list covers worldwide, a set of countries and many cities. It is not every country. For country trends, pass the `countryCode` of a `Country` entry as `country` to `/tw-v2/trends`; city entries also carry a country code, so check the place type. For city trends, pass the WOEID instead. Locations keep X's order. `placeType.name` is `Supername` for worldwide, `Country` for countries and `Town` for cities; a few other place types also appear. The response is not paginated.

**Endpoint guide:** https://tweetapi.com/docs/trends/locations
**Usage cost:** 1 API unit per billable request

**Parameters:** None

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/trends/locations" \
  -H "X-API-Key: YOUR_API_KEY"
```


================================================================================
AUTH ENDPOINTS
================================================================================

### POST /tw-v2/auth/login

**Description:**
Authenticate a Twitter account and retrieve session cookies for use with interaction endpoints. A billable response consumes 50 API units. Separately limited to 60 requests per minute per TweetAPI account.

**Endpoint guide:** https://tweetapi.com/docs/auth/login
**Usage cost:** 50 API units per billable request

**Request Body:**
- username (string, required): Account username or email
- password (string, required): Account password
- twoFactorSecret (string, optional): TOTP secret (min 16 chars) for accounts with 2FA enabled. Used to auto-generate 2FA codes.
- proxy (string, required): Proxy in format 'hostname:port@username:password'. Required for all login requests.
- country (string, required): Assigned ISO 3166-1 alpha-2 code for the public IP used to reach X. Use the proxy exit country (for example, 'US'). All assigned codes are accepted, and input is normalized to uppercase.

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/auth/login" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "yourUsername",
  "password": "yourPassword",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "country": "US"
}'
```


================================================================================
X CHAT (Encrypted DMs) ENDPOINTS
================================================================================

### POST /tw-v2/xchat/setup

**Description:**
Initialize X Chat (encrypted DMs) for your account. This is a required first step before sending encrypted messages. You must have X Chat already set up in the official app before using this endpoint. Call it again when the API says the stored keys need refreshing, for example after an X Chat PIN change.

**Endpoint guide:** https://tweetapi.com/docs/xchat/setup
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- userId (string, required): Your Twitter user ID (numeric string)
- pin (string, required): Your X Chat PIN (4-6 digits) set up in the official app
- proxy (string, optional): Proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/xchat/setup" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "userId": "1001937475184068444",
  "pin": "123456"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/xchat/conversations

**Description:**
Get a list of all X Chat conversations in your inbox. Returns conversation metadata including participants and timestamps. This endpoint does not require /xchat/setup since it only returns metadata, not decrypted message content.

**Endpoint guide:** https://tweetapi.com/docs/xchat/conversations
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- cursor (string, optional): Pagination cursor from previous response
- graphSnapshotId (string, optional): Graph snapshot ID from previous response (required together with cursor for page 2+)
- limit (number, optional): Number of conversations per page (1-100, default 50)
- proxy (string, optional): Proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/xchat/conversations" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "cursor": "50",
  "graphSnapshotId": "bf0310dd-d428-4de1-9815-435bc3791406"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/xchat/send

**Description:**
Send an end-to-end encrypted direct message via X Chat. Prerequisite - You must call /xchat/setup first before sending messages.

**Endpoint guide:** https://tweetapi.com/docs/xchat/send
**Usage cost:** 10 API units per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- recipientId (string, required): Twitter user ID of the message recipient (numeric string)
- message (string, required): The message text to send (max 10,000 characters)
- conversationToken (string, optional): Optional conversation token returned by a previous XChat request
- conversationKeyVersion (string, optional): Optional version identifier for the supplied encrypted conversation key
- encryptedConversationKey (string, optional): Optional encrypted conversation key returned by XChat setup or history
- proxy (string, optional): Proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/xchat/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "recipientId": "9876543210987654321",
  "message": "Hello! This is an encrypted message."
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/xchat/history

**Description:**
Get decrypted conversation history for an end-to-end encrypted X Chat conversation. Returns messages in decrypted plaintext with metadata. Prerequisite - You must call /xchat/setup first before fetching history.

**Endpoint guide:** https://tweetapi.com/docs/xchat/history
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- conversationId (string, required): Conversation ID in format 'userId1:userId2' (both user IDs separated by colon)
- cursor (string, optional): Pagination cursor from previous response (nextCursor value)
- limit (number, optional): Maximum number of messages to return (1-200, default 200)
- proxy (string, optional): Proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/xchat/history" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "conversationId": "1001937475184068444:9876543210987654321"
}'
```

--------------------------------------------------------------------------------

### POST /tw-v2/xchat/can-dm

**Description:**
Check if users can receive X Chat encrypted DMs. Returns chat permissions including whether they have X Chat enabled and a public key for encryption. Use this endpoint to verify recipients before attempting to send encrypted messages.

**Endpoint guide:** https://tweetapi.com/docs/xchat/can-dm
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- userIds (array, required): Array of Twitter user IDs to check (1-100 IDs per request)
- proxy (string, optional): Proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/xchat/can-dm" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "userIds": ["1000000000000000001", "1000000000000000002"]
}'
```


================================================================================
UNENCRYPTED DM (Legacy) ENDPOINTS
================================================================================

### POST /tw-v2/interaction/send-dm

**Description:**
Send a direct message to a user with optional media attachment. Supports images, GIFs, and videos with automatic type detection and processing. Maximum 1 media item per DM.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/send-dm
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- conversationId (string, required): Conversation ID. For 1-on-1 conversations: 'userId1-userId2' (e.g., '123456789-987654321'). For group conversations: single conversation ID (e.g., '1234567890')
- text (string, required): The text content of the direct message (max 10,000 characters)
- requestId (string, optional): Optional UUID for request tracking. Auto-generated if not provided.
- media (array, optional): Optional array with 1 media object. Can be {url: string} or {data: string, type: string}
- proxy (string, required): Proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/send-dm" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "proxy": "proxy.example.com:8080@proxyUser:proxyPass",
  "conversationId": "123456789-987654321",
  "text": "Hello! This is a test DM.",
  "media": [{"url":"https://example.com/link-94089/profile-29900/image.jpg"}]
}'
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/dm-permissions

**Description:**
Check if you can send direct messages to specific users. Verifies DM permissions for up to 50 recipient IDs at once.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/dm-permissions
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- recipientIds (string, required): Comma-separated list of user IDs to check (max 50 IDs, e.g., '123456789,987654321')
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/dm-permissions?authToken=YOUR_AUTH_TOKEN&recipientIds=123456789,987654321" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/inbox-initial-state

**Description:**
Get the initial state of your DM inbox. Returns conversations, messages, user data, and inbox timeline cursors for pagination. Use the returned cursor for polling updates via dm-user-updates endpoint.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/inbox-initial-state
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/inbox-initial-state?authToken=YOUR_AUTH_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/inbox-timeline-trusted

**Description:**
Get paginated trusted conversations timeline. Use the cursor from inbox-initial-state or previous response to fetch next page of trusted DM conversations.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/inbox-timeline-trusted
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- cursor (string, required): Cursor for pagination. Get from inbox-initial-state or previous response.
- filterLowQuality (boolean, optional): Filter out low quality conversations (default false)
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/inbox-timeline-trusted?authToken=YOUR_AUTH_TOKEN&cursor=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/inbox-timeline-untrusted

**Description:**
Get paginated untrusted/filtered conversations timeline. Use the cursor from inbox-initial-state or previous response to fetch next page of untrusted DM conversations (message requests).

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/inbox-timeline-untrusted
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- cursor (string, required): Cursor for pagination. Get from inbox-initial-state or previous response.
- filterLowQuality (boolean, optional): Filter out low quality conversations (default false)
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/inbox-timeline-untrusted?authToken=YOUR_AUTH_TOKEN&cursor=1234567890" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/conversation

**Description:**
Get messages from a specific DM conversation. Returns conversation details, messages, and user data. Supports pagination with cursor for loading message history.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/conversation
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- conversationId (string, required): Conversation ID. For 1-on-1 conversations: 'userId1-userId2' (e.g., '123456789-987654321'). For group conversations: single conversation ID (e.g., '1234567890')
- cursor (string, optional): Pagination cursor for loading older messages. Obtained from previous response.
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/conversation?authToken=YOUR_AUTH_TOKEN&conversationId=123456789-987654321" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### GET /tw-v2/interaction/dm-user-updates

**Description:**
Poll for new DM updates and changes. Use the cursor from inbox-initial-state or previous dm-user-updates response to check for new messages, conversations, and updates. Ideal for real-time DM monitoring.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/dm-user-updates
**Usage cost:** 1 API unit per billable request

**Parameters:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- cursor (string, required): Update cursor from inbox-initial-state or previous dm-user-updates response. Required for polling.
- proxy (string, optional): Optional proxy in format 'host:port@user:pass'

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/interaction/dm-user-updates?authToken=YOUR_AUTH_TOKEN&cursor=UPDATE_CURSOR_HERE" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------------------------------------------------------

### POST /tw-v2/interaction/accept-conversation

**Description:**
Accept an untrusted DM conversation (message request). Moves the conversation from the untrusted inbox to the trusted inbox, allowing future messages from the sender. This is the equivalent of clicking "Accept" on a message request in the web UI.

**Endpoint guide:** https://tweetapi.com/docs/unencrypted-dm/accept-conversation
**Usage cost:** 1 API unit per billable request

**Request Body:**
- authToken (string, required): Account authentication token (auth_token cookie value)
- conversationId (string, required): Conversation ID. For 1-on-1 conversations: 'userId1-userId2' (e.g., '123456789-987654321'). For group conversations: single conversation ID (e.g., '1234567890')
- proxy (string, optional): Optional proxy in format 'hostname:port@username:password'

**Example:**
```bash
curl -X POST "https://api.tweetapi.com/tw-v2/interaction/accept-conversation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authToken": "YOUR_AUTH_TOKEN",
  "conversationId": "123456789-987654321"
}'
```


================================================================================
ACCOUNT ENDPOINTS
================================================================================

### GET /tw-v2/account/usage

**Description:**
Check the API units left on the calling API key. Returns the free or subscription allowance, the spendable PAYG balance, and the effective rate limit. This request costs no units; it counts against the rate limit only.

**Usage notes:**

`availableUnits` is the plan's remaining units plus spendable PAYG units. `plan` is null for a PAYG-only account, and `payg` is null until a PAYG wallet is funded. Expired PAYG units count as 0. A 503 with `Retry-After` means the allowance state is temporarily unavailable; wait and retry.

**Endpoint guide:** https://tweetapi.com/docs/account/usage
**Usage cost:** Free (0 API units); counts against the rate limit only

**Parameters:** None

**Example:**
```bash
curl -X GET "https://api.tweetapi.com/tw-v2/account/usage" \
  -H "X-API-Key: YOUR_API_KEY"
```


================================================================================
ADDITIONAL INFORMATION
================================================================================

**Response Format:**
- Public operations return JSON; response fields and status codes vary by operation. Use the matching OpenAPI response schema and example
- Normalized public reads often contain "data"; paginated reads can also contain "pagination". Login and messaging have operation-specific shapes
- Do not assume that every success uses one envelope. Errors use the shape described under Errors above

**Data Types:**
- Timestamp formats vary by field: ISO 8601 strings, numeric Unix milliseconds, and X-formatted date strings occur. Follow each response schema
- IDs are strings (snowflake IDs, e.g., "1234567890")
- Cursors are opaque strings used for pagination

**Pagination:**
- Many endpoints support cursor-based pagination
- Start without a cursor unless the endpoint says otherwise. For /tw-v2/search, pass the previous response's pagination.nextCursor as the next request's cursor; stop when that value is null
- Other endpoints can place cursors differently. Use each response schema and endpoint guide for the next-cursor field and end condition

**Support:**
- Email: support@tweetapi.com
- Telegram: @tweetapi

END OF DOCUMENTATION