Users

Overview

The Users endpoints are the most comprehensive set of endpoints in the API, providing access to virtually any information about Twitter users. You can retrieve user profiles, timelines, followers, following lists, media, likes, and much more. These endpoints support both username and user ID lookups, making them flexible for various use cases.

Key Features

• User Profiles: Complete user information including bio, metrics, verification status
• Timelines: Get user tweets, replies, and media
• Social Graph: Access followers and following lists with full user data
• Bulk Operations: Fetch multiple users in a single request
• Flexible Lookup: Use either username or user ID
• Pagination: Efficient cursor-based pagination for large datasets
• Verified Followers: Special endpoint for verified follower lists

Username vs User ID

• Username (screen_name): The @handle (e.g., "elonmusk") - can change
• User ID: Numeric identifier (e.g., "44196397") - permanent and never changes

Best Practice: Use User ID when possible for stability, as usernames can change. Use username for user-friendly interfaces.

Authentication

All endpoints require authentication via the X-API-KEY header:

X-API-KEY: YOUR_API_KEY

For detailed authentication information, see our Authentication Guide.

Endpoints

Get User by Username

Retrieves detailed user information using the username (screen name). This is the most user-friendly way to look up accounts.

Endpoint: GET /user/by/username/{username}

Path Parameters

Request Examples

cURL:

curl --request GET \
  --url 'https://<direct.gateway>/user/by/username/elonmusk' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch('https://<direct.gateway>/user/by/username/elonmusk', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const data = await response.json();

Python:

import requests
 
response = requests.get(
    'https://<direct.gateway>/user/by/username/elonmusk',
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
data = response.json()

Response Example

{
  "user": {
    "result": {
      "__typename": "User",
      "rest_id": "44196397",
      "legacy": {
        "screen_name": "elonmusk",
        "name": "Elon Musk",
        "description": "https://t.co/9qhgzJ69UQ",
        "followers_count": 226943745,
        "friends_count": 1217,
        "statuses_count": 86681,
        "favourites_count": 174705,
        "listed_count": 164432,
        "media_count": 4162,
        "verified": false,
        "is_blue_verified": true,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/...",
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/...",
        "created_at": "Tue Jun 02 20:12:29 +0000 2009",
        "location": ""
      },
      "is_blue_verified": true,
      "professional": {
        "rest_id": "1679729435447275522",
        "professional_type": "Creator"
      }
    }
  }
}

Response Fields

Notes

• Usernames are case-insensitive
• If username doesn't exist, returns 404
• Usernames can change, but user IDs are permanent

Get User by User ID

Retrieves detailed user information using the numeric user ID. This is more reliable than username lookups since IDs never change.

Endpoint: GET /user/{userId}

Path Parameters

Request Examples

cURL:

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch('https://<direct.gateway>/user/44196397', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const data = await response.json();

Response Format

Same as "Get User by Username" endpoint above.

When to Use User ID vs Username

• Use User ID: For permanent references, database storage, API integrations
• Use Username: For user-facing features, search functionality, when user provides @handle

Get User Tweets

Retrieves tweets from a specific user's timeline. This is one of the most commonly used endpoints for building timelines and feeds.

Endpoint: GET /user/{userId}/tweets

Path Parameters

Query Parameters

Request Examples

With User ID:

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/tweets?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

With Username:

curl --request GET \
  --url 'https://<direct.gateway>/user/-1/tweets?count=20&username=elonmusk' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

// Using user ID
const response = await fetch('https://<direct.gateway>/user/44196397/tweets?count=20', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
 
// Using username
const response = await fetch('https://<direct.gateway>/user/-1/tweets?count=20&username=elonmusk', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});

Response Example

{
  "user": {
    "result": {
      "timeline": {
        "timeline": {
          "instructions": [
            {
              "type": "TimelineAddEntries",
              "entries": [
                {
                  "entryId": "tweet-1972376013297586551",
                  "content": {
                    "itemContent": {
                      "tweet_results": {
                        "result": {
                          "rest_id": "1972376013297586551",
                          "legacy": {
                            "full_text": "Tweet content here",
                            "created_at": "Wed Jun 14 12:00:00 +0000 2023",
                            "favorite_count": 5234,
                            "retweet_count": 1234,
                            "reply_count": 567
                          },
                          "views": {
                            "count": "29584831"
                          }
                        }
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  },
  "cursor": {
    "top": "...",
    "bottom": "..."
  }
}

Common Use Cases

1. User Timeline: Display a user's recent tweets
2. Content Analysis: Analyze a user's posting patterns
3. Feed Building: Create custom feeds based on specific users
4. Monitoring: Track what specific users are posting

Notes

• Results are ordered by most recent first
• Use pagination to get historical tweets
• Private account tweets require appropriate access
• Maximum 100 tweets per request

Get User Tweets and Replies

Retrieves both tweets and replies from a user's timeline. This provides a complete view of a user's activity, including their responses to other users.

Endpoint: GET /user/{userId}/tweetsAndReplies

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/tweetsAndReplies?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Format

Similar to "Get User Tweets" but includes both original tweets and replies.

Use Cases

• Complete Activity Feed: Show everything a user posts
• Engagement Analysis: See how users interact with others
• Conversation Tracking: Follow user conversations

Get User Media

Retrieves all media (images, videos) posted by a user. This is useful for building media galleries or analyzing visual content.

Endpoint: GET /user/{userId}/media

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/media?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "user": {
    "result": {
      "timeline": {
        "timeline": {
          "instructions": [
            {
              "type": "TimelineAddEntries",
              "entries": [
                {
                  "content": {
                    "itemContent": {
                      "tweet_results": {
                        "result": {
                          "legacy": {
                            "extended_entities": {
                              "media": [
                                {
                                  "media_url_https": "https://pbs.twimg.com/media/...",
                                  "type": "photo",
                                  "sizes": {
                                    "large": {
                                      "w": 2048,
                                      "h": 1536
                                    }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Use Cases

• Media Galleries: Display user's photos and videos
• Content Curation: Find visual content from specific users
• Media Analysis: Analyze types of media users post

Get User Followers

Retrieves the list of users following a specific account. This is essential for social graph analysis and audience insights.

Endpoint: GET /user/{userId}/followers

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/followers?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "user": {
    "result": {
      "timeline": {
        "timeline": {
          "instructions": [
            {
              "type": "TimelineAddEntries",
              "entries": [
                {
                  "content": {
                    "itemContent": {
                      "user_results": {
                        "result": {
                          "rest_id": "123456789",
                          "legacy": {
                            "screen_name": "follower_user",
                            "name": "Follower Name",
                            "followers_count": 1523,
                            "verified": false
                          }
                        }
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  },
  "cursor": {
    "top": "...",
    "bottom": "..."
  }
}

Use Cases

• Audience Analysis: Understand who follows an account
• Influencer Identification: Find influential followers
• Social Graph Mapping: Build network visualizations
• Follower Growth Tracking: Monitor follower acquisition

Important Notes

• Rate Limits: Follower lists can be very large - use pagination carefully
• Private Accounts: Private account followers may not be accessible
• Performance: Large follower lists require multiple paginated requests

Get User Following

Retrieves the list of accounts that a user is following. This is the inverse of the followers endpoint.

Endpoint: GET /user/{userId}/following

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/following?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Format

Same structure as followers endpoint, but returns accounts the user follows.

Use Cases

• Interest Analysis: Understand what accounts a user follows
• Content Discovery: Find similar accounts
• Network Analysis: Map following relationships

Get User Following IDs

Retrieves only the user IDs of accounts a user is following, without full user objects. This is more efficient when you only need IDs.

Endpoint: GET /user/{userId}/following/ids

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/following/ids?count=100' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "ids": [
    "123456789",
    "987654321",
    "555666777"
  ],
  "next_cursor": 1234567890,
  "next_cursor_str": "1234567890",
  "previous_cursor": 0,
  "previous_cursor_str": "0"
}

Use Cases

• Efficient Lookups: When you only need IDs for batch operations
• Relationship Checking: Quickly check if user A follows user B
• Bulk Operations: Use IDs with bulk user endpoint

Get Verified Followers

Retrieves only verified followers of a user. This is useful for identifying influential or notable followers.

Endpoint: GET /user/{userId}/verified-followers

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/44196397/verified-followers?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Use Cases

• Influencer Discovery: Find verified accounts following a user
• Credibility Analysis: Assess account credibility through verified followers
• Network Mapping: Map verified account relationships

Get Tweets by Username

An exclusive endpoint that allows fetching tweets directly using a username, without needing the user ID first.

Endpoint: GET /user/username/{username}/tweets

Path Parameters

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/user/username/elonmusk/tweets?count=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Benefits

• Convenience: No need to look up user ID first
• User-Friendly: Works directly with usernames users provide
• Simplified Workflow: One request instead of two

Convert Username to User ID

Converts a username to its corresponding user ID. Useful when you need the permanent ID for storage or other operations.

Endpoint: GET /username/to/id/{username}

Path Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/username/to/id/elonmusk' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "user_id": "44196397",
  "username": "elonmusk"
}

Use Cases

• Database Storage: Convert usernames to IDs for permanent storage
• API Workflows: Get ID before making other API calls
• Data Normalization: Standardize on user IDs in your system

Get Multiple Users (Bulk)

Retrieves detailed information for multiple users in a single request. This is much more efficient than making individual requests.

Endpoint: GET /users/bulk

Query Parameters

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/users/bulk?ids=44196397,123456789,987654321' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "data": [
    {
      "user": {
        "result": {
          "rest_id": "44196397",
          "legacy": {
            "screen_name": "elonmusk",
            "name": "Elon Musk",
            "followers_count": 226943745
          }
        }
      }
    },
    {
      "user": {
        "result": {
          "rest_id": "123456789",
          "legacy": {
            "screen_name": "example_user",
            "name": "Example User",
            "followers_count": 12345
          }
        }
      }
    }
  ]
}

Benefits

• Efficiency: Fetch up to 100 users in one request
• Rate Limit Friendly: Counts as one request instead of many
• Performance: Faster than sequential requests

Best Practices

• Batch user lookups when possible
• Use this endpoint for follower/following lists when you need full user data
• Combine with following/ids endpoint for optimal workflow

Pagination

All list endpoints (followers, following, tweets, etc.) use cursor-based pagination. See our Pagination Guide for detailed information and examples.

Best Practices

User-Specific Tips

• Use User IDs for storage: User IDs never change, usernames can change
• Use bulk endpoints: Fetch multiple users with /users/bulk instead of individual requests
• Cache user profiles: User profiles don't change frequently, cache for 5-15 minutes
• Handle private accounts: Always check for 403 errors and handle gracefully

Troubleshooting

FAQ

Can I get followers of private accounts?

Only if your API credentials have access to the private account (e.g., you follow them). Otherwise, you'll receive a 403 Forbidden error.

What's the maximum number of users I can fetch in bulk?

The /users/bulk endpoint supports up to 100 user IDs per request. For more users, make multiple requests.

How do I handle username changes?

Since usernames can change, always store user IDs in your database. Use usernames for user-facing features, but convert them to IDs for storage and API calls.

Can I get historical follower counts?

The API returns current follower counts. For historical data, you would need to track counts over time yourself.

What's the difference between verified and is_blue_verified?

• verified: Legacy verification (blue checkmark from Twitter)
• is_blue_verified: Twitter Blue subscription verification

How often should I refresh user data?

User profiles don't change frequently. Cache user data for 5-15 minutes depending on your use case. Follower counts can change more often, so consider shorter cache times for metrics.

Can I get a user's email address?

No, email addresses are never exposed through the API for privacy reasons.

Related Documentation

• Tweets Endpoints - Get user tweets and replies
• Search Endpoints - Search for users
• Using Pagination Cursors - Detailed pagination guide
• Error Handling Guide - Comprehensive error handling
• Rate Limits Guide - Understanding rate limits
• Best Practices - API usage best practices