Make Your First Request

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

Get your Bearer Token

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

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

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"

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
Search recent posts
Get user's posts

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

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

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

Using code instead of cURL

Python
JavaScript
Official SDKs

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())

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));

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.

​Quick start with cURL

​Step-by-step guide

​Request more data with fields

​More examples

​Using code instead of cURL

​Tools for testing