Skip to content

make-your-first-request.mdx

Latest commit

 

History

History
232 lines (187 loc) · 5.92 KB

make-your-first-request.mdx

File metadata and controls

232 lines (187 loc) · 5.92 KB
title Make Your First Request
sidebarTitle Make Your First Request
icon rocket
description Get up and running with the X API in minutes
keywords
first request
getting started
API quickstart
make API request
cURL
API example
sample code

import { Button } from '/snippets/button.mdx';

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

In the [Developer Console](https://console.x.com), navigate to your app and copy the Bearer Token. Start with one of these beginner-friendly endpoints: 
| Endpoint | What it does |
|:---------|:-------------|
| [User lookup](/x-api/users/lookup/introduction) | Get user profile by username or ID |
| [Post lookup](/x-api/posts/lookup/introduction) | Get post by ID |
| [Recent search](/x-api/posts/search/introduction) | Search posts from the last 7 days |
Use cURL, Postman, or your preferred HTTP client: 
```bash
# Look up a user by username
curl "https://api.x.com/2/users/by/username/xdevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```
Responses are JSON. The primary data is in the `data` field: 
```json
{
  "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

```bash curl "https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at,public_metrics" \ -H "Authorization: Bearer $BEARER_TOKEN" ``` ```bash curl "https://api.x.com/2/tweets/search/recent?query=from:xdevelopers&tweet.fields=created_at" \ -H "Authorization: Bearer $BEARER_TOKEN" ``` ```bash 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())

  </Tab>
  <Tab title="JavaScript">
```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));
For production use, we recommend the official SDKs:

They handle authentication, pagination, and rate limiting automatically.

Tools for testing

Visual API testing with our collection. Examples in multiple languages. Full endpoint documentation.

Troubleshooting

- Check that your Bearer Token is correct - Ensure the token hasn't been regenerated - Verify the `Authorization` header format: `Bearer YOUR_TOKEN` - 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 - 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

Understand OAuth for user-context requests. Discover what you can build. Faster development with official libraries. Ideas for what to create.