Integration Guide

Key concepts and best practices for integrating User lookup

This guide covers the key concepts you need to integrate the User lookup endpoints into your application.

---

Authentication

All X API v2 endpoints require authentication. Choose the method that fits your use case:

Method	Best for	Can access private metrics?
OAuth 2.0 App-Only	Server-to-server, public data	No
OAuth 2.0 Authorization Code with PKCE	User-facing apps	Yes (for authorized user’s data)
OAuth 1.0a User Context	Legacy integrations	Yes (for authorized user’s data)

App-Only authentication

For public user data, use a Bearer Token:

cURL

shellscript

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

User Context authentication

Required for the authenticated user endpoint (/2/users/me):

cURL

shellscript

curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

The /2/users/me endpoint only works with User Context authentication. App-Only tokens will return an error.

---

Fields and expansions

The X API v2 returns minimal data by default. Use fields and expansions to request exactly what you need.

Default response

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

Available fields

user.fields

Field	Description
created_at	Account creation timestamp
description	User bio
entities	Parsed URLs in bio
location	User-defined location
pinned_tweet_id	Pinned Post ID
profile_image_url	Avatar URL
protected	Whether account is protected
public_metrics	Follower/following counts
url	Website URL
verified	Verification status
withheld	Withholding information

tweet.fields (requires pinned_tweet_id expansion)

Field	Description
created_at	Post creation timestamp
text	Post content
public_metrics	Engagement counts
entities	Hashtags, mentions, URLs

Example with fields

cURL

shellscript

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

Response with expansions

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Welcome to the X Developer Platform!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

Fields and expansions guide

Learn more about customizing responses

---

Batch lookups

Look up multiple users in a single request:

cURL (by IDs)

shellscript

curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Batch requests are limited to 100 users. Use multiple requests for larger datasets.

---

Error handling

Common errors

Status	Error	Solution
400	Invalid request	Check parameter formatting
401	Unauthorized	Verify authentication credentials
403	Forbidden	Check App permissions
404	Not Found	User doesn’t exist or was suspended
429	Too Many Requests	Wait and retry (see rate limits)

Suspended or deleted users

If a user is suspended or deleted:

• Single user lookup returns 404
• Multi-user lookup omits the user from results with an errors array

{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

Protected users

For protected accounts you don’t follow:

• Basic info (id, name, username) is available
• Protected content (pinned Post) may be restricted
• protected: true indicates the account status

---

Best practices

Batch requests

Use multi-user endpoints to fetch up to 100 users at once, reducing API calls.

Request only needed fields

Specify only the fields you need to minimize response size.

Cache user data

Cache user profiles locally to reduce repeated requests.

Handle errors gracefully

Check for partial errors in batch responses.

---

Next steps

API Reference

Complete endpoint documentation

Data dictionary

All available objects and fields

Sample code

Working code examples

Error handling

Handle errors gracefully