# X API Documentation
## Introduction
The X API enables programmatic access to the X platform, allowing developers to interact with core elements such as Posts, Direct Messages, Spaces, Lists, Users, and more. It is designed to facilitate advanced integrations and automation.
---
## Overview of API Versions
### X API v2
The v2 of the X API is now production-ready, and developers are encouraged to migrate to this version for new projects.
- **Why migrate?**
Improved data objects, new request parameters, enhanced metrics, and more features.
- **Migration resources:**
- [Data Dictionary](https://developer.x.com/en/docs/twitter-api/data-dictionary.html)
- [Using Fields and Expansions](https://developer.x.com/en/docs/twitter-api/data-dictionary/using-fields-and-expansions.html)
- [Metrics](https://developer.x.com/en/docs/twitter-api/metrics.html)
- [Annotations](https://developer.x.com/en/docs/twitter-api/annotations.html)
- [Conversation ID](https://developer.x.com/en/docs/twitter-api/conversation-id.html)
- [Migration Guide](https://developer.x.com/en/docs/twitter-api/migrate.html)
- [Endpoint Map](https://developer.x.com/en/docs/twitter-api/migrate/twitter-api-endpoint-map.html)
---
## API Access Levels
| Tier | Description | Cost | Limitations |
|-------------|---------------------|--------|--------------|
| **Free** | For testing and low-volume use cases | Free | - 500 posts/month<br>- 100 reads/month<br>- 1 Project, 1 App, 1 Environment |
| **Basic** | Hobbyists and prototypes | $175/month annually or $200/month | - 3,000 posts/month (user level)<br>- 50,000 posts (app level)<br>- 10,000 reads/month<br>- 1 Project, 2 Apps/environments |
| **Pro** | Startup scaling | $4,500/month annually or $5,000/month | - 1,000,000 GET posts/month<br>- 300,000 posts (posting)<br>- 1 Project, 3 Apps/environments |
| **Enterprise**| Large businesses and commercial projects | Custom pricing | - Custom, includes full stream features, engagement metrics, backfill, and managed services |
[More on v2 access levels](https://developer.x.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-leve)
---
## How to Migrate to v2
To migrate your current integration:
- Visit the [Migration Hub](https://developer.x.com/en/docs/twitter-api/migrate.html) for resources, guides, and data format updates.
- Review the [Endpoint Map](https://developer.x.com/en/docs/twitter-api/migrate/twitter-api-endpoint-map.html) for endpoint changes.
[Learn more](https://developer.x.com/en/docs/twitter-api/migrate.html)
---
## What to Build with the X API
- Moderate conversations for safety
- Enable creation and expression
- Measure and analyze activity
- Improve community experiences
- Curate and recommend content
- Impact the greater good
[Explore ideas here](https://developer.x.com/en/docs/twitter-api/what-to-build.html)
---
## Tools to Get Started
### Client Libraries
Check out curated client libraries, both official and community-supported:
[Browse libraries](https://developer.x.com/en/docs/twitter-api/tools-and-libraries.html)
### Postman Collection
Explore the v2 endpoints with the official Postman collection:
[Get started with Postman](https://developer.x.com/en/docs/tools-and-libraries/using-postman.html)
### Sample Code
Sample apps and code snippets are available on GitHub:
[GitHub Repository](https://github.com/xdevplatform)
[Get sample code](https://github.com/xdevplatform)
---
## Support and Community
- **Help Center:** [Support resources and FAQs](https://developer.x.com/en/support/twitter-api.html)
- **Forum:** [Developer community](https://twittercommunity.com/)
- **Feedback:** [Provide product feedback](https://twitterdevfeedback.uservoice.com/forums/930250-twitter-api)
---
## Additional Resources
- [Developer Policy and Terms](https://developer.x.com/en/more/developer-terms/agreement-and-policy)
- [Follow @XDevelopers](http://x.com/xdevelopers)
- [X Platform](https://x.com/):
- [Status](https://docs.x.com/status)
- [Help & Resources](https://help.x.com/)
- [Privacy Center](https://privacy.x.com/)
- [Transparency Center](https://transparency.x.com/)
- [Download X App](https://help.x.com/resources/accessibility)
- [Company Info](https://about.x.com/en)
- [Careers & Investors](https://careers.x.com/ | https://investor.twitterinc.com/)
- [Legal & Policies](https://help.x.com/rules-and-policies/twitter-cookies)
---
# API Reference (Markdown Format)
## Fetch User Details
### Endpoint
`GET /2/users/by/username/:username`
### Description
Fetches user details by username.
### Query Parameters
| Name | Type | Description | Required | Default |
|-------------|----------|-----------------------------------|----------|---------|
| `user.fields` | string | Comma-separated list of user fields to include | No | None |
| `expansions` | string | Comma-separated list of fields to expand | No | None |
### Request Example (curl)
```bash
curl -X GET "https://api.x.com/2/users/by/username/elonmusk?user.fields=created_at,description&expansions=pinned_tweet_id" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Successful Response
```json
{
"data": {
"id": "44196397",
"name": "Elon Musk",
"username": "elonmusk",
"created_at": "2009-06-20T12:01:54.000Z",
"description": "Tesla, SpaceX, Neuralink, The Boring Company, and more..."
},
"includes": {
"tweets": [
// expanded data
]
}
}
```
### Error Response
```json
{
"errors": [{"message": "Unauthorized", "code": 401}]
}
```
---
## Post a Tweet
### Endpoint
`POST /2/tweets`
### Description
Creates a new tweet.
### Body Data
| Name | Type | Description | Required | Default |
|--------------|----------|--------------------------------------------|----------|---------|
| `text` | string | The text content of the tweet | Yes | None |
| `reply` | object | Reply settings, if replying to a tweet | No | None |
### Example JSON Body
```json
{
"text": "Hello world! #XAPI"
}
```
### Request Example (curl)
```bash
curl -X POST "https://api.x.com/2/tweets" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text": "Hello world! #XAPI"}'
```
### Successful Response
```json
{
"data": {
"id": "1453489038376136707",
"text": "Hello world! #XAPI"
}
}
```
### Error Response
```json
{
"errors": [{"message": "Unauthorized", "code": 401}]
}
```
---
## Additional Endpoints (Examples)
- **Get Mentions:** `GET /2/users/:id/mentions`
- **Get Timelines:** `GET /2/users/:id/tweets`
- **Space Details:** `GET /2/spaces/:id`
*(Details, request parameters, and responses vary; refer to the [full data dictionary](https://developer.x.com/en/docs/twitter-api/data-dictionary.html) for comprehensive info.)*
---
## Notes:
- All endpoints require an OAuth 2.0 Bearer Token with appropriate scopes.
- Use HTTPS for all API requests.
- Handle rate limits as specified per access level.
---
## Conclusion
The X API offers extensive capabilities to build innovative applications, monitor activity, and integrate deeply with the platform. Explore the resources, start with sample code, and join the developer community for support.
**End of Document**
