---
title: "User by username"
method: GET
path: "/user/by/username/{username}"
tags: ["Users"]
---

# User by username

`GET /user/by/username/{username}`

## Request

- Base URL: `https://api.twittrapi.com`
- URL: `https://api.twittrapi.com/user/by/username/{username}`
- Auth: API key in header `X-API-KEY`

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

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

## Path parameters

- `username` string, required

## Query parameters

- `format` 'raw' | 'simple'

## Response `200`

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.

- union: format=simple: the simple-format schema. Default (raw): X's JSON, passthrough.
  - UserResult: Simple format: one user (null when the handle does not exist)
    - `data` User, required
      - `id` string, required
      - `username` string, required: Handle without @
      - `name` string, required: Display name
      - `description` string, required: Bio, t.co links expanded
      - `location` string, required
      - `url` string, nullable, required: Website, expanded
      - `createdAt` string, date-time, nullable, required
      - `avatarUrl` string, nullable, required
      - `bannerUrl` string, nullable, required
      - `verified` boolean, required: Blue check
      - `verifiedType` string, nullable, required: e.g. Business or Government
      - `protected` boolean, required: Private account
      - `counts` object, required
        - `followers` integer, required
        - `following` integer, required
        - `tweets` integer, required
        - `likes` integer, required
        - `media` integer, required
        - `listed` integer, required
      - `pinnedTweetIds` string[], required
      - `isAutomated` boolean, required
  - RawPassthrough: X's own JSON (raw format, the default), passed through unchanged. The shape is X's and can change; see https://www.twittrapi.com/docs/response-format.

## Other responses

- `400`: The username contains characters X blocks, or X returned an error.
- `401`: Missing or unknown API key. Not charged.
- `402`: No balance left, or the trial expired. Not charged. Top up in the dashboard.
- `403`: Key deactivated, or the endpoint is not in your plan (trial keys and account actions). Not charged.
- `422`: The username is not 2 to 15 letters, digits or underscores.
- `429`: Rate limit for your key exceeded. Not charged. No Retry-After header: back off exponentially.
- `500`: Something failed on our side or between us and X. Refunded (400, 407, 408, 409 or a 5xx error are refunded). Retry with backoff.

---

[API](https://skmtc.dev/twittrapi/apis/twittrapi-api.md) · [All operations](https://skmtc.dev/twittrapi/apis/twittrapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/twittrapi/apis/twittrapi-api/revisions/0618e38b54c2?raw)