Answers
X user ID or @handle: which one should I store?
Short answer
Store the numeric user ID as the key and the @handle as a label. Handles are unique but can change; the ID does not. okdata X account profile looks accounts up by handle and returns the ID, for $0.0004, so keep both and check that the ID still matches on every refresh.
Every X account has two identifiers. The user ID is a number such as 2244994945 that X assigns once and never changes. The handle, the @name in the profile URL, is what people type and share, and the owner can change it whenever they like. X's own data dictionary describes usernames as "unique but subject to change". A tracker keyed on handles breaks quietly the day a brand rebrands.
How they differ
| User ID | Handle (username) | |
|---|---|---|
| Example | 2244994945, or 19 digits for newer accounts |
@TwitterDev |
| Changes? | Never | Whenever the owner renames |
| Unique? | Yes | Yes, at any one time |
| Length | Short for old accounts; newer ones are 64-bit Snowflake IDs | Typically up to 15 characters |
Because newer user IDs are Snowflake IDs, they also encode roughly when the account was created; see reading the time from an X ID.
What to store
One row per account: user_id as the primary key, then username, name and the date you last saw that handle. Treat the handle as a display value that you refresh, never as the join key for posts, followers or campaigns.
How okdata handles it
X account profile and X account posts take username, with or without the @, and return id (the user ID) and username (the current handle). Every post from X post detail or search carries author.id and author.username too. There is no lookup by numeric user ID in the catalog, which is the reason to keep both.
When a handle goes stale, two things can happen. The lookup returns not_found, which is still charged as one call. Or the old handle has been taken by another account and you get a different profile, with a different id. Either way, read one of the account's posts you stored earlier with post detail: post IDs do not change, and author.username gives the current handle.
| Job | Calls | Cost |
|---|---|---|
| Resolve one handle to its ID | 1 | $0.0004 |
| Refresh 300 tracked accounts | 300 | $0.12 |
| Repair a renamed account via a known post | 1 | $0.0003 |
Example
import os, requests
API = "https://api.okdata.online"
H = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
def get(path, **params):
return requests.get(API + path, headers=H, params=params, timeout=60).json()
def refresh(row):
"""row = {"user_id": "...", "username": "...", "known_post_id": "..."}"""
body = get("/v1/x/users/get", username=row["username"], fields="id,username,followers")
if body["code"] == "ok" and body["data"]["item"]["id"] == row["user_id"]:
return {**row, "followers": body["data"]["item"]["followers"]}
post = get("/v1/x/posts/get", id=row["known_post_id"], fields="author.id,author.username")
if post["code"] == "ok" and post["data"]["item"]["author"]["id"] == row["user_id"]:
return {**row, "username": post["data"]["item"]["author"]["username"], "renamed": True}
return {**row, "status": "check by hand"}
Limits
- A suspended or deleted account returns
not_foundfrom both routes; there is no way to read its current state. - Keep IDs as strings. Newer user IDs exceed what a JavaScript number holds exactly.
- Display names (
name) change even more often than handles and are not unique. Never match accounts on them.
For follower counts across a list of accounts, see getting a Twitter account's follower count.
Sources
Where people asked this (read 2026-11-12)
Updated