User Lookup Quickstart

This guide walks you through looking up users by their ID or username. Reference for the X API v2 standard tier covering quickstart.

This guide walks you through looking up users by their ID or username.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• Your App’s Bearer Token

---

Look up by ID

Single user

cURL

shellscript

curl "https://api.x.com/2/users/2244994945?\
user.fields=created_at,description,verified,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get user by ID
response = client.users.get(
    "2244994945",
    user_fields=["created_at", "description", "verified", "public_metrics"]
)

print(f"Name: {response.data.name}")
print(f"Username: {response.data.username}")
print(f"Followers: {response.data.public_metrics.followers_count}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Get user by ID
const response = await client.users.get("2244994945", {
  userFields: ["created_at", "description", "verified", "public_metrics"],
});

console.log(`Name: ${response.data?.name}`);
console.log(`Username: ${response.data?.username}`);
console.log(`Followers: ${response.data?.public_metrics?.followers_count}`);

Response

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "The voice of the X developer community",
    "verified": true,
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}

Multiple users

Look up to 100 users at once:

cURL

shellscript

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get multiple users by ID
response = client.users.get_users(
    ids=["2244994945", "783214", "6253282"],
    user_fields=["username", "verified"]
)

for user in response.data:
    print(f"{user.username} - Verified: {user.verified}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Get multiple users by ID
const response = await client.users.getUsers({
  ids: ["2244994945", "783214", "6253282"],
  userFields: ["username", "verified"],
});

response.data?.forEach((user) => {
  console.log(`${user.username} - Verified: ${user.verified}`);
});

---

Look up by username

Single user

cURL

shellscript

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get user by username
response = client.users.get_by_username(
    "XDevelopers",
    user_fields=["created_at", "description", "verified"]
)

print(f"ID: {response.data.id}")
print(f"Name: {response.data.name}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Get user by username
const response = await client.users.getByUsername("XDevelopers", {
  userFields: ["created_at", "description", "verified"],
});

console.log(`ID: ${response.data?.id}`);
console.log(`Name: ${response.data?.name}`);

Multiple users

cURL

shellscript

curl "https://api.x.com/2/users/by?\
usernames=XDevelopers,X,elonmusk&\
user.fields=created_at,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get multiple users by username
response = client.users.get_users_by_usernames(
    usernames=["XDevelopers", "X", "elonmusk"],
    user_fields=["created_at", "verified"]
)

for user in response.data:
    print(f"{user.username} - {user.created_at}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Get multiple users by username
const response = await client.users.getUsersByUsernames({
  usernames: ["XDevelopers", "X", "elonmusk"],
  userFields: ["created_at", "verified"],
});

response.data?.forEach((user) => {
  console.log(`${user.username} - ${user.created_at}`);
});

---

Available fields

Field	Description
created_at	Account creation date
description	User bio
profile_image_url	Avatar URL
verified	Verification status
public_metrics	Follower/following counts
location	User-defined location
url	User’s website
protected	Protected account status
pinned_tweet_id	Pinned Post ID

---

Handle errors

User not found

{
  "errors": [
    {
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with username: [nonexistent_user]."
    }
  ]
}

Protected user

Protected users’ data is still returned, but you won’t be able to access their Posts unless you follow them.

---

Next steps

Authenticated user

Get the current user

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation