Make Your First Request

Send your first X API v2 request in minutes using cURL or Postman, including authentication, endpoint selection, and parsing the JSON response.

This guide walks you through making your first X API request. You’ll need a developer account with app credentials before starting.

---

Quick start with cURL

The fastest way to test the API is with cURL. Let’s look up a user:

curl "https://api.x.com/2/users/by/username/xdevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Replace $BEARER_TOKEN with your actual Bearer Token. You’ll get a response like:

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers"
  }
}

---

Step-by-step guide

1. Get your Bearer Token

   In the Developer Console, navigate to your app and copy the Bearer Token.

2. Choose an endpoint

   Start with one of these beginner-friendly endpoints:

   Endpoint	What it does
   User lookup	Get user profile by username or ID
   Post lookup	Get post by ID
   Recent search	Search posts from the last 7 days

3. Make the request

   Use cURL, Postman, or your preferred HTTP client:

   # Look up a user by username
   curl "https://api.x.com/2/users/by/username/xdevelopers" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   
4. Parse the response

   Responses are JSON. The primary data is in the data field:

   {
     "data": {
       "id": "2244994945",
       "name": "X Developers",
       "username": "xdevelopers"
     }
   }
   

---

Request more data with fields

By default, endpoints return minimal fields. Use the fields parameter to request additional data:

curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Response:

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "The voice of the X Developer Platform",
    "public_metrics": {
      "followers_count": 570842,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}

Learn more about fields →

---

More examples

Look up a post

curl "https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Search recent posts

curl "https://api.x.com/2/tweets/search/recent?query=from:xdevelopers&tweet.fields=created_at" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Get user's posts

curl "https://api.x.com/2/users/2244994945/tweets?max_results=5" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

Using code instead of cURL

Python

import requests

bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/users/by/username/xdevelopers"

headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers)

print(response.json())

JavaScript

const bearerToken = "YOUR_BEARER_TOKEN";
const url = "https://api.x.com/2/users/by/username/xdevelopers";

fetch(url, {
  headers: { Authorization: `Bearer ${bearerToken}` }
})
  .then(res => res.json())
  .then(data => console.log(data));

Official SDKs

For production use, we recommend the official SDKs:

• Python SDK
• TypeScript SDK

They handle authentication, pagination, and rate limiting automatically.

---

Tools for testing

Postman

Visual API testing with our collection.

Sample code

Examples in multiple languages.

API reference

Full endpoint documentation.

---

Troubleshooting

401 Unauthorized

• Check that your Bearer Token is correct
• Ensure the token hasn’t been regenerated
• Verify the Authorization header format: Bearer YOUR_TOKEN

403 Forbidden

• Your app may not have access to this endpoint
• Some endpoints require user-context authentication (OAuth 1.0a or 2.0)
• Check your app’s permissions in the Developer Console

429 Too Many Requests

• You’ve hit a rate limit
• Check the x-rate-limit-reset header for when to retry
• Implement exponential backoff in your code

Full error reference →

---

Next steps

Learn authentication

Understand OAuth for user-context requests.

Explore endpoints

Discover what you can build.

Use an SDK

Faster development with official libraries.

Build something

Ideas for what to create.