Login API • TweetAPI Docs

POST/tw-v2/auth/login

This endpoint costs 50 request units per successful call.

Description

Authenticate a platform account and retrieve session cookies for use with interaction endpoints. A successful response consumes 50 request units.

Rate Limit: This endpoint is limited to 60 requests per minute.

Request Body

Parameter	Type	Required	Description
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.

Country and proxy matching

country identifies the public IP location used for the X login request, not the account's profile country. Set it to the proxy's exit country and keep the same proxy for the complete login attempt. For example, use US for a proxy that exits in the United States. A mismatched country and proxy location can cause X to reject the login.

Code Examples

const body = {
  username: 'yourUsername',
  password: 'yourPassword',
  proxy: 'proxy.example.com:8080@proxyUser:proxyPass',
  country: 'US'
};

const response = await fetch('https://api.tweetapi.com/tw-v2/auth/login', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

const data = await response.json();
console.log(data);

Response

Success Response (200 OK)

200

{
  "status": "success",
  "data": {
    "cookies": {
      "auth_token": "YOUR_AUTH_TOKEN",
      "ct0": "YOUR_CT0_TOKEN",
      "twid": "YOUR_TWID_COOKIE",
      "kdt": "YOUR_KDT_TOKEN",
      "__cf_bm": "YOUR_CF_BM_COOKIE"
    },
    "user": {
      "id": "1009530492076271",
      "username": "exampleUser",
      "name": "Sample User 82107"
    },
    "timestamp": "2025-11-28T10:41:10.196Z"
  }
}

Error Responses

400s Errors

400VALIDATION_ERROR

401INVALID_CREDENTIALS

401TWO_FACTOR_REQUIRED

401INVALID_TWO_FACTOR_CODE

403ACCOUNT_SUSPENDED

403ACCOUNT_LOCKED

429RATE_LIMITED

500s Errors

502PROXY_ERROR

503LOGIN_RUNTIME_UNAVAILABLE

Login