twitterapi-io

Interact with Twitter/X via TwitterAPI.io — search tweets, get user info, post tweets, like, retweet, follow, send DMs, and more. Covers all 58 endpoints (V2). Use when the user wants to read or write Twitter data.

# TwitterAPI.io skill v3.7.2

Access Twitter/X data and perform actions via [TwitterAPI.io](https://twitterapi.io) REST API.
Use TwitterAPI.io REST API for read, write, webhook, and stream operations.

Docs: https://docs.twitterapi.io | Dashboard: https://twitterapi.io/dashboard

---

## Setup

1. Get API key: https://twitterapi.io/dashboard ($0.10 free credits, no CC)
2. Store the key in a `.env` file or your shell's secure config (do not use raw `export` with the actual key in the terminal -- it gets saved to shell history).
3. For write actions, you also need `login_cookies` from v2 login + residential `proxy`.

Base URL: `https://api.twitterapi.io`
Auth header: `X-API-Key: $TWITTERAPI_IO_KEY` (all requests)

---

## Pricing (credit-based, 1 USD = 100,000 credits)

| Resource | Credits | Approx $/1K |
|----------|---------|-------------|
| Tweets (per returned tweet) | 15 | $0.15 |
| Profiles (per returned profile) | 18 | $0.18 |
| Profiles batch 100+ (per profile) | 10 | $0.10 |
| Followers (per returned follower) | 15 | $0.15 |
| Verified followers (per follower) | 30 | $0.30 |
| Minimum per API call | 15 | $0.00015 |
| List endpoint calls | 150 | $0.0015 |
| Check follow relationship | 100 | $0.001 |
| Get article | 100 | $0.001 |
| Community info | 20 | $0.0002 |
| Write actions (tweet, like, RT, follow) | 200-300 | $0.002-0.003 |
| Login | 300 | $0.003 |

Note: If the API returns 0 or 1 item, you are still charged the minimum (15 credits).

---

## QPS (rate limits) -- balance-based

| Account Balance (Credits) | QPS Limit |
|---------------------------|-----------|
| < 1,000 (free tier) | 1 req / 5 sec |
| >= 1,000 | 3 |
| >= 5,000 | 6 |
| >= 10,000 | 10 |
| >= 50,000 | 20 |

---

## API Notes

All V1 endpoints have been removed from the API. Use V2 (`_v2` suffix) endpoints for write operations.
V3 endpoints were taken offline by TwitterAPI.io in March 2026. Use V2 for write operations. For mission-critical tweet posting, consider Twitter's official API.

### login_cookie vs login_cookies -- API Inconsistency

The API has an inconsistency in naming:
- `user_login_v2` **response** returns the field as `login_cookie` (singular)
- All v2 **action** endpoints expect the field as `login_cookies` (plural)

**Always use `login_cookies` (plural) in request bodies.** The value is the same string.

---

## Response schemas

### Tweet object (from search, replies, etc.)
```json
{
  "type": "tweet",
  "id": "1234567890",
  "url": "https://x.com/user/status/1234567890",
  "text": "Tweet content...",
  "source": "Twitter Web App",
  "retweetCount": 5,
  "replyCount": 2,
  "likeCount": 42,
  "quoteCount": 1,
  "viewCount": 1500,
  "bookmarkCount": 3,
  "createdAt": "Sun Feb 08 12:00:00 +0000 2026",
  "lang": "en",
  "isReply": false,
  "inReplyToId": null,
  "inReplyToUserId": null,
  "inReplyToUsername": null,
  "conversationId": "1234567890",
  "displayTextRange": [0, 280],
  "isLimitedReply": false,
  "author": { "...User Object..." },
  "entities": {
    "hashtags": [{ "text": "AI", "indices": [10, 13] }],
    "urls": [{ "display_url": "example.com", "expanded_url": "https://example.com", "url": "https://t.co/xxx" }],
    "user_mentions": [{ "id_str": "123", "name": "Someone", "screen_name": "someone" }]
  },
  "quoted_tweet": null,
  "retweeted_tweet": null
}
```

### User object
```json
{
  "type": "user",
  "id": "999888777",
  "userName": "elonmusk",
  "name": "Elon Musk",
  "url": "https://x.com/elonmusk",
  "isBlueVerified": true,
  "verifiedType": "none",
  "profilePicture": "https://pbs.twimg.com/...",
  "coverPicture": "https://pbs.twimg.com/...",
  "description": "Bio text...",
  "location": "Mars",
  "followers": 200000000,
  "following": 800,
  "canDm": false,
  "favouritesCount": 50000,
  "mediaCount": 2000,
  "statusesCount": 30000,
  "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
  "pinnedTweetIds": ["1234567890"],
  "isAutomated": false,
  "possiblySensitive": false,
  "profile_bio": {
    "description": "Bio text...",
    "entities": {
      "description": { "urls": [] },
      "url": { "urls": [{ "display_url": "example.com", "expanded_url": "https://example.com" }] }
    }
  }
}
```

### Paginated list response
```json
{
  "tweets": [ "...array of Tweet Objects..." ],
  "has_next_page": true,
  "next_cursor": "cursor_string...",
  "status": "success",
  "msg": null
}
```

---

## Endpoint reference

For detailed endpoint documentation with curl examples, consult the reference files:

- For READ endpoint documentation (33 endpoints), consult `references/read-endpoints.md`
- For WRITE V2 endpoint documentation (19 endpoints), consult `references/write-endpoints.md`
- For Webhook and Stream endpoint documentation (6 endpoints), consult `references/webhook-stream-endpoints.md`
- For the complete endpoint index table (all 58 endpoints), consult `references/endpoint-index.md`

---

## X/Twitter platform degradation notice (March 2026)

**CRITICAL**: Around March 5, 2026, Twitter/X disabled or degraded several advanced search features due to high platform usage. This affects ALL Twitter API providers (not just TwitterAPI.io) because TwitterAPI.io proxies Twitter's own search infrastructure.

### What's broken

| Feature | Status | Impact |
|---------|--------|--------|
| `since:DATE` / `until:DATE` in search | **DEGRADED** | Returns incomplete results (often only 7-20 tweets per query regardless of actual volume) |
| Search pagination | **BROKEN** | Cursor-based pagination returns the SAME page of results repeatedly instead of advancing |
| `since_time:UNIX` / `until_time:UNIX` | **WORKS** | Alternative date format using Unix timestamps -- returns correct date range |
| `within_time:Nh` | **WORKS** | Relative time filter (e.g., `within_time:72h`) |
| `get_user_last_tweets` pagination | **WORKS** | User timeline cursor pagination is unaffected |
| `get_user_mentions` sinceTime/untilTime | **WORKS** | Server-side Unix timestamp parameters (not search operators) |
| Webhook filter rules | **WORKS** | Real-time collection unaffected (but webhook URL may be lost during API key rotation) |

### Workarounds for date-range queries

**Instead of** (broken):
```
$BTC since:2026-03-06_00:00:00_UTC until:2026-03-07_00:00:00_UTC
```

**Use** (working):
```
$BTC since_time:1741219200 until_time:1741305600
```

Convert dates to Unix timestamps: `date -d "2026-03-06T00:00:00Z" +%s` or use Python: `int(datetime(2026,3,6,tzinfo=timezone.utc).timestamp())`

**Pagination workaround**: Since pagination is broken, use **hourly time windows** instead of paginating through a large result set. Each 1-hour window returns a unique set of ~7-16 tweets (page 1 only). This gives ~250 unique tweets per coin per day across 24 windows.

**For user timelines**: Use `GET /twitter/user/last_tweets` with cursor pagination (works normally). Paginate backwards through the user's timeline, then client-side filter by `createdAt` date. This completely bypasses search operators.

### Webhook URL gotcha

When a TwitterAPI.io API key is rotated (e.g., after account data reset), the webhook filter rules may be restored but the **webhook URL is NOT automatically restored**. You must manually re-set the webhook URL in the dashboard at https://twitterapi.io/tweet-filter-rules after any key rotation event.

**Monitoring tip**: Check that `collection_type='webhook'` tweets are still arriving. If rules are active but zero webhook tweets arrive for 30+ minutes, verify the webhook URL is configured.

---

## Twitter search syntax (for `query` param in advanced_search)

| Operator | Example | Description | Status (Mar 2026) |
|----------|---------|-------------|-------------------|
| `from:` | `from:elonmusk` | Tweets by user | Working |
| `to:` | `to:elonmusk` | Replies to user | Working |
| `"..."` | `"exact phrase"` | Exact match | Working |
| `OR` | `cat OR dog` | Either term | Working |
| `-` | `-spam` | Exclude term | Working |
| `since:` / `until:` | `since:2026-01-01_00:00:00_UTC` | D