For AI

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_found from 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

  1. X API data dictionary: user id and usernamedocs.x.com · read
  2. X API docs: X IDsdocs.x.com · read

Where people asked this (read 2026-11-12)

Updated

Connect once, then just ask.

Every new key comes with $0.10 to try it. One sentence connects your agent.

Start free
Connect your AI

Paste this into your agent

Read https://okdata.online/agents.md and set up okdata for me; my key is in the OKDATA_API_KEY environment variable.

Claude Code, Cursor, Codex and other agents that can open a link set themselves up from it.

MCP serverhttps://api.okdata.online/mcp