---
name: x
description: "Use when building applications that access X's public data:
  searching posts, looking up users, managing direct messages, creating content,
  analyzing trends, or building real-time streaming applications. Agents should
  reach for this skill when users request API integration, data retrieval,
  authentication setup, or troubleshooting X API issues."
metadata:
  mintlify-proj: x
  version: "1.0"
---

# 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 data, manage content, access trends, and build real-time streaming applications. The API uses pay-per-usage pricing with no subscriptions. Key files and commands: Bearer Token (app-only auth), OAuth 1.0a/2.0 (user context), endpoints at `https://api.x.com/2/`, official SDKs in Python and TypeScript. Primary docs: https://docs.x.com/x-api/introduction

## When to use

Reach for this skill when:
- A user needs to search posts, retrieve user profiles, or access historical data
- Building integrations that read/write posts, manage DMs, or handle user relationships
- Setting up authentication (Bearer Token, OAuth 1.0a, OAuth 2.0)
- Debugging API errors (401, 403, 429) or rate limit issues
- Implementing real-time streaming with filtered stream or webhooks
- Optimizing queries with fields, expansions, and pagination
- Calculating costs or monitoring usage in the Developer Console

## Quick reference

### Authentication methods

| Method | Use case | Scope |
|--------|----------|-------|
| Bearer Token (app-only) | Read public data, no user context | App-level requests |
| OAuth 1.0a User Context | Access private data, act on behalf of user | User-level requests |
| OAuth 2.0 Authorization Code | Modern user auth with scopes | User-level requests |
| OAuth 2.0 App-Only | App-only with OAuth 2.0 | App-level requests |

### Core endpoints

| Resource | Endpoint | Method | Purpose |
|----------|----------|--------|---------|
| User lookup | `/2/users/by/username/:username` | GET | Get user by handle |
| Post lookup | `/2/tweets/:id` | GET | Get post by ID |
| Recent search | `/2/tweets/search/recent` | GET | Search last 7 days |
| Full-archive search | `/2/tweets/search/all` | GET | Search all posts (paid) |
| Filtered stream | `/2/tweets/search/stream` | GET | Real-time posts matching rules |
| Create post | `/2/tweets` | POST | Publish a post |
| Direct messages | `/2/dm_conversations` | POST/GET | Send/receive DMs |

### Field parameters

| Object | Parameter | Example |
|--------|-----------|---------|
| Post | `tweet.fields` | `created_at,public_metrics,lang` |
| User | `user.fields` | `created_at,description,public_metrics` |
| Media | `media.fields` | `url,preview_image_url,alt_text` |
| Poll | `poll.fields` | `options,voting_status` |

### Rate limit headers

```
x-rate-limit-limit: 450        # Max requests in window
x-rate-limit-remaining: 425    # Requests left
x-rate-limit-reset: 1705420800 # Unix timestamp when window resets
```

## Decision guidance

### When to use Bearer Token vs OAuth

| Scenario | Use Bearer Token | Use OAuth |
|----------|------------------|-----------|
| Reading public posts/users | ✓ | — |
| Accessing private DMs | — | ✓ |
| Publishing posts | — | ✓ |
| Building user-facing app | — | ✓ |
| Server-to-server integration | ✓ | — |

### When to use search vs filtered stream

| Need | Use search | Use filtered stream |
|------|-----------|-------------------|
| Historical data (7+ days old) | ✓ | — |
| Real-time posts as published | — | ✓ |
| One-time query | ✓ | — |
| Continuous monitoring | — | ✓ |
| Complex queries | ✓ | ✓ |

### When to use fields vs expansions

| Goal | Use fields | Use expansions |
|------|-----------|-----------------|
| Get more data on primary object | ✓ | — |
| Include related objects (author, media) | — | ✓ |
| Reduce response size | — | — |
| Customize response structure | ✓ | ✓ |

## Workflow

1. **Verify credentials exist**: Check that the user has a Developer Console account at console.x.com with an app created. Confirm they have Bearer Token or OAuth credentials saved securely.

2. **Choose authentication method**: Determine if the task requires app-only (Bearer Token) or user-context (OAuth 1.0a/2.0) authentication. App-only is simpler for public data; OAuth is required for private data or user actions.

3. **Select the endpoint**: Identify which endpoint matches the task (search, lookup, create, stream, etc.). Check the API reference for required parameters and available fields.

4. **Build the request**: Construct the URL with query parameters. Add `fields` to request specific data. Add `expansions` to include related objects. Use pagination tokens for large result sets.

5. **Handle authentication**: Add the `Authorization` header with Bearer Token or OAuth signature. For OAuth 1.0a, sign the request. For OAuth 2.0, include the access token.

6. **Execute and parse**: Make the HTTP request. Check response status. Parse JSON response. Data is in the `data` field; related objects are in `includes`.

7. **Monitor rate limits**: Check `x-rate-limit-remaining` in response headers. If approaching zero, implement exponential backoff before retrying. Wait until `x-rate-limit-reset` timestamp.

8. **Verify results**: Confirm the response contains expected fields. Check for errors in the `errors` array. Validate data types and values match documentation.

## Common gotchas

- **Missing fields in response**: By default, endpoints return minimal fields. Always add `tweet.fields`, `user.fields`, etc. to get the data you need.
- **Expansions without fields**: Adding an expansion (e.g., `expansions=author_id`) includes the related object but you still need `user.fields` to get user details.
- **Bearer Token for private data**: Bearer Token only works for public data. Private DMs, bookmarks, and user-context actions require OAuth.
- **Rate limit window resets**: Rate limits are per 15-minute window (or 24 hours for some endpoints). The window doesn't reset on demand—wait until `x-rate-limit-reset` timestamp.
- **429 errors without backoff**: Hitting a 429 (rate limit) without implementing exponential backoff will cause repeated failures. Always check headers and wait.
- **Pagination token expiry**: Pagination tokens expire after a period. If a token fails, restart from the beginning with a new request.
- **Query length limits**: Recent search allows 512 characters; full-archive allows 1,024. Queries longer than this will fail silently or be truncated.
- **Streaming connection drops**: Filtered stream connections drop after 20 seconds without data. Implement reconnection logic with exponential backoff.
- **Owned reads pricing**: Requests for your own data (posts, bookmarks, followers) are cheaper ($0.001 per resource) than third-party data. Verify you're using the right endpoint.

## Verification checklist

Before submitting work:

- [ ] Authentication credentials are stored securely (not in code)
- [ ] Correct authentication method chosen (Bearer Token vs OAuth)
- [ ] Required `fields` parameters added to request
- [ ] Expansions used correctly with corresponding field parameters
- [ ] Rate limit headers checked in response
- [ ] Error responses parsed and handled (401, 403, 429, etc.)
- [ ] Pagination implemented for large result sets
- [ ] Response data validated against API reference
- [ ] Exponential backoff implemented for 429 errors
- [ ] Streaming connections include reconnection logic

## Resources

- **Comprehensive page listing**: https://docs.x.com/llms.txt
- **API Introduction & endpoints**: https://docs.x.com/x-api/introduction
- **Authentication guide**: https://docs.x.com/fundamentals/authentication/overview
- **Rate limits & error handling**: https://docs.x.com/x-api/fundamentals/rate-limits

---

> For additional documentation and navigation, see: https://docs.x.com/llms.txt