Skip to content

make-your-first-request.mdx

Latest commit

 

History

History
232 lines (187 loc) · 6.02 KB

make-your-first-request.mdx

File metadata and controls

232 lines (187 loc) · 6.02 KB
title Make Your First Request
sidebarTitle Make Your First Request
icon rocket
description Send your first X API v2 request in minutes using cURL or Postman, including authentication, endpoint selection, and parsing the JSON response.
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.