# User by username

`GET https://api.twittrapi.com/user/by/username/{username}`

Profile of one account by handle, including its numeric user ID.

HTML page: https://www.twittrapi.com/docs/reference/user-by-username-username

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `username` | path | string | yes |  | Handle, with or without a leading @. 2 to 15 characters: letters, digits and underscore. |

Every read endpoint also accepts `format=simple` (or the header `X-Response-Format: simple`) for compact, flat JSON with a fixed schema. Same price.

## Response

Raw JSON of X's UserByScreenName query (data.user.result, with rest_id and legacy profile fields). When X returns no user, the API answers 200 with {"data": {}, "userExists": false}.

With `format=simple`: {data: User}, or {data: null} when the handle does not exist.

## Errors

| Status | When |
| --- | --- |
| 422 | The username is not 2 to 15 letters, digits or underscores. |
| 400 | The username contains characters X blocks, or X returned an error. |

Shared errors (401 missing key, 402 no balance, 429 rate limit, 5xx) are listed on https://www.twittrapi.com/docs/helpful-infos/error-handling. Calls that fail with 400, 408, 409 or a 5xx error are refunded.

## Example request

curl:

```bash
curl 'https://api.twittrapi.com/user/by/username/jack' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

Python:

```python
from twittrapi import TwittrAPI

client = TwittrAPI(api_key="YOUR_API_KEY")
data = client.users.get_by_username("jack")
```

Node.js:

```js
import { TwittrAPI } from "twittrapi";

const client = new TwittrAPI({ apiKey: process.env.TWITTRAPI_API_KEY });
const data = await client.users.getByUsername("jack");
```

RapidAPI:

```bash
curl 'https://twitter-aio.p.rapidapi.com/user/by/username/jack' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
  --header 'x-rapidapi-host: twitter-aio.p.rapidapi.com'
```

## Example response

Shortened: arrays keep their first items and long strings are cut.

Raw (default):

```json
{
  "data": {
    "user": {
      "result": {
        "__typename": "User",
        "affiliates_highlighted_label": {
          "label": {
            "badge": {
              "url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg"
            },
            "description": "X",
            "url": {
              "url": "https://twitter.com/X",
              "urlType": "DeepLink"
            },
            "userLabelDisplayType": "Badge",
            "userLabelType": "BusinessLabel"
          }
        },
        "avatar": {
          "image_url": "https://pbs.twimg.com/profile_images/1683501992314798080/xl1POYLw_normal.jpg"
        },
        "business_account": {},
        "core": {
          "created_at": "Sat Dec 14 04:35:55 +0000 2013",
          "name": "Developers",
          "screen_name": "XDevelopers"
        },
        "creator_subscriptions_count": 0,
        "dm_permissions": {
          "can_dm": true
        },
        "follow_request_sent": false,
        "has_graduated_access": true,
        "has_hidden_subscriptions_on_profile": false,
        "highlights_info": {
          "can_highlight_tweets": true,
          "highlighted_tweets": "4"
        },
        "id": "VXNlcjoyMjQ0OTk0OTQ1",
        "is_blue_verified": true,
        "is_profile_translatable": false,
        "legacy": {
          "default_profile": false,
          "default_profile_image": false,
          "description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X API.",
          "entities": {
            "description": {},
            "url": {
              "urls": [
                {
                  "display_url": "docs.x.com",
                  "expanded_url": "https://docs.x.com/",
                  "indices": [
                    0,
                    23
                  ],
                  "url": "https://t.co/NIwHVIVyrN"
                }
              ]
            }
          },
          "fast_followers_count": 0,
          "favourites_count": 2758,
          "follow_request_sent": false,
          "followers_count": 698074,
          "friends_count": 770,
          "has_custom_timelines": true,
          "is_translator": false,
          "listed_count": 2977,
          "media_count": 832,
          "needs_phone_verification": false,
          "normal_followers_count": 698074,
          "notifications": false,
          "pinned_tweet_ids_str": [
            "2019881223666233717"
          ],
          "possibly_sensitive": false,
          "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1690213128",
          "profile_interstitial_type": "",
          "statuses_count": 4376,
          "time_zone": "",
          "translator_type": "regular",
          "url": "https://t.co/NIwHVIVyrN",
          "utc_offset": 0,
          "want_retweets": false,
          "withheld_description": "",
          "withheld_scope": ""
        },
        "legacy_extended_profile": {},
… (68 more lines)
```

Simple (`format=simple`):

```json
{
  "data": {
    "id": "2244994945",
    "username": "XDevelopers",
    "name": "Developers",
    "description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X API.",
    "location": "127.0.0.1",
    "url": "https://docs.x.com/",
    "createdAt": "2013-12-14T04:35:55Z",
    "avatarUrl": "https://pbs.twimg.com/profile_images/1683501992314798080/xl1POYLw.jpg",
    "bannerUrl": "https://pbs.twimg.com/profile_banners/2244994945/1690213128",
    "verified": true,
    "verifiedType": "Business",
    "protected": false,
    "counts": {
      "followers": 698074,
      "following": 770,
      "tweets": 4376,
      "likes": 2758,
      "media": 832,
      "listed": 2977
    },
    "pinnedTweetIds": [
      "2019881223666233717"
    ],
    "isAutomated": false
  }
}
```