X

Files (1)

• SKILL.md

SKILL.md (first lines)

# X API Skill

## Product summary

The X API provides programmatic access to X's public conversation through modern REST endpoints. Agents use it to search posts, retrieve user profiles, stream real-time content, manage lists and bookmarks, send direct messages, and access engagement metrics. The API uses pay-per-usage pricing with no subscriptions. Key endpoints are at `https://api.x.com/2/`. Authentication uses Bearer tokens (app-only) or OAuth 1.0a/2.0 (user context). Official SDKs exist for Python (`xdk`) and TypeScript (`@xdevplatform/xdk`). See the [X API documentation](https://docs.x.com/x-api/introduction) for comprehensive reference.

## When to use

Reach for this skill when:

- **Searching posts**: Find posts by keyword, user, date, or advanced operators (recent 7 days or full archive)
- **Retrieving user data**: Look up user profiles by ID or username, get follower/following lists
- **Streaming real-time posts**: Monitor posts matching filter rules with near real-time delivery
- **Managing user interactions**: Create/delete posts, like, repost, bookmark, follow/unfollow users
- **Accessing metrics**: Get engagement data (likes, reposts, replies, impressions) for posts
- **Working with lists**: Create, update, delete curated lists; manage list members
- **Direct messaging**: Send and receive private messages between users
- **Analyzing trends**: Retrieve trending topics by location or personalized trends
- **Handling compliance**: Check post/user deletion status, stream compliance events

Do not use this skill for: Ads API (separate skill), website embeds (X for Websites), authentication setup (use fundamentals docs), or account management (use Developer Console).

## Quick reference

### Authentication methods

| Method | Use case | Header format |
|:-------|:---------|:--------------|
| Bearer Token (app-only) | Public data, no user context | `Authorization: Bearer YOUR_TOKEN` |
| OAuth 1.0a | User-context actions (post, like, follow) | Signature-based; SDKs handle it |
| OAuth 2.0 | User-context with PKCE flow | Bearer token from 3-legged flow |

### Essential endpoints

| Endpoint | Method | Purpose |
|:---------|:-------|:---------|
| `/2/tweets/search/recent` | GET | Search posts from last 7 days |
| `/2/tweets/search/all` | GET | Search full archive (back to 2006) |
| `/2/tweets/search/stream` | GET | Stream posts matching rules (persistent connection) |
| `/2/tweets/search/stream/rules` | GET/POST | Manage stream filter rules |
| `/2/tweets/:id` | GET | Look up single post by ID |
| `/2/tweets` | GET | Look up multiple posts by IDs |
| `/2/users/by/username/:username` | GET | Get user by username |
| `/2/users/:id` | GET | Get user by ID |
| `/2/users/:id/tweets` | GET | Get user's posts |
| `/2/users/:id/followers` | GET | Get user's followers |
| `/2/tweets` | POST | Create a post |
| `/2/tweets/:id` | DELETE | Delete a post |
| `/2/users/:id/likes` | POST | Like a post |
| `/2/users/:id/following` | POST | Follow a user |

### Field and expansion parameters

All GET endpoints return minimal data by default. Use parameters to request additional data:

```bash
# Request additional post fields
?tweet.fields=created_at,public_metrics,author_id

# Request additional user fields
?user.fields=description,public_metrics,verified

# Include related objects (author, media, etc.)
?expansions=author_id,attachments.media_keys

# Combine with field parameters for related objects
?expansions=author_id&user.fields=username,description
```

Common field combinations:
- **Post analytics**: `tweet.fields=created_at,public_metrics,possibly_sensitive`
- **User profiles**: `user.fields=created_at,description,location,public_metrics,verified`
- **Full context**: `tweet.fields=created_at,author_id,conversation_id&expansions=author_id&user.fields=username`

### Rate limits

Check response headers for limit status:

```
x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800
```

Sample per-endpoint limits (15-minute windows):
- User lookup: 300/app, 900/user
- Recent search: 450/app, 300/user
- Post lookup: 450/app, 900/user
- Create post: 10,000/24hrs (app), 100/15min (user)
- Filtered stream: 50/15min connections, 1000 rules max

See [rate limits reference](/x-api/fundamentals/rate-limits) for complete table.

### Response format

Successful responses (200, 201):

```json
{
  "data": {
    "id": "123",
    "text": "Hello world",
    "created_at": "2024-01-15T12:00:00.000Z"
  },
  "includes": {
    "users": [{"id": "456", "username": "example"}]
  }
}
```

Error responses (4xx, 5xx):

```json
{
  "title": "Invalid Request",
  "detail": "The 'query' parameter is required.",
  "type": "https://api.x.com/2/problems/invalid-request"
}
```

From meetshukla/quill, MIT.

More from meetshukla/quill