> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter profile search, lookup & audience counts

> Look up a Twitter or X profile by username or user ID. Retrieve the bio, follower and following counts, verification status, location, and links. 1 credit.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-twitter-profile-lookup-200">
      ```json theme={null}
      {
        "id": "9876543210",
        "username": "elonmusk",
        "name": "Elon Musk",
        "description": "CEO of Tesla, SpaceX, and X",
        "followers": 150000000,
        "following": 500,
        "verified": true
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-twitter-profile-lookup-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-twitter-profile-lookup-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="402" id="response-x-twitter-profile-lookup-402">
      ```json theme={null}
      {
        "error": "insufficient_credits",
        "message": "Insufficient credits. Top up or subscribe to continue."
      }
      ```
    </Tab>

    <Tab title="404" id="response-x-twitter-profile-lookup-404">
      ```json theme={null}
      {
        "error": "user_not_found",
        "message": "X user not found. Check the username."
      }
      ```
    </Tab>

    <Tab title="424" id="response-x-twitter-profile-lookup-424">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="429" id="response-x-twitter-profile-lookup-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="502" id="response-x-twitter-profile-lookup-502">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-twitter-profile-lookup-503">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "Xquik is busy right now. Retry shortly."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="coins" color="#5c3327">
  **1 credit per call** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit · Direct [MPP](/mpp/machine-payments-protocol): USD 0.00015 per call
</Callout>

<Tip>
  See [Read Data Richness](/guides/tweet-profile-api-fields) for every optional
  profile field. Xquik omits fields that X does not supply.
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://xquik.com/api/v1/x/users/username \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const username = "username";
  const response = await fetch(`https://xquik.com/api/v1/x/users/${username}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const profileRow = {
    user_id: data.id,
    username: data.username,
    display_name: data.name,
    bio: data.description ?? null,
    follower_count: data.followers ?? null,
    following_count: data.following ?? null,
    verified: data.verified ?? false,
    verified_type: data.verifiedType ?? null,
    profile_url: data.url ?? null,
    profile_image_url: data.profilePicture ?? null,
    created_at: data.createdAt ?? null,
    unavailable_reason: data.unavailableReason ?? null,
  };

  process.stdout.write(`${JSON.stringify(profileRow)}\n`);
  ```

  ```python Python theme={null}
  import json
  import requests

  response = requests.get(
      "https://xquik.com/api/v1/x/users/username",
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  profile_row = {
      "user_id": data["id"],
      "username": data["username"],
      "display_name": data["name"],
      "bio": data.get("description"),
      "follower_count": data.get("followers"),
      "following_count": data.get("following"),
      "verified": data.get("verified", False),
      "verified_type": data.get("verifiedType"),
      "profile_url": data.get("url"),
      "profile_image_url": data.get("profilePicture"),
      "created_at": data.get("createdAt"),
      "unavailable_reason": data.get("unavailableReason"),
  }
  print(json.dumps(profile_row))
  ```

  ```go Go theme={null}
  package main

  import (
    "encoding/json"
    "io"
    "log"
    "net/http"
    "os"
  )

  func main() {
    username := "username"
    req, err := http.NewRequest("GET", "https://xquik.com/api/v1/x/users/"+username, nil)
    if err != nil {
      log.Fatal(err)
    }
    req.Header.Set("x-api-key", "xq_your_api_key_here")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
      log.Fatal(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
      log.Fatal(err)
    }

    var user map[string]any
    if err := json.Unmarshal(body, &user); err != nil {
      log.Fatal(err)
    }

    row := map[string]any{
      "user_id":            user["id"],
      "username":           user["username"],
      "display_name":       user["name"],
      "bio":                user["description"],
      "follower_count":     user["followers"],
      "following_count":    user["following"],
      "verified":           user["verified"],
      "verified_type":      user["verifiedType"],
      "profile_url":        user["url"],
      "profile_image_url":  user["profilePicture"],
      "created_at":         user["createdAt"],
      "unavailable_reason": user["unavailableReason"],
    }
    if err := json.NewEncoder(os.Stdout).Encode(row); err != nil {
      log.Fatal(err)
    }
  }
  ```
</CodeGroup>

Use `GET /x/users/{id}` when a workflow needs one profile row for CRM
enrichment, lead scoring, account monitoring, or support triage. Store
`user_id`, `username`, `display_name`, `bio`, `follower_count`,
`following_count`, `verified`, `verified_type`, `profile_url`,
`profile_image_url`, `created_at`, and `unavailable_reason`. Do not log
the full lookup response.

<CardGroup cols={2}>
  <Card title="Profile row" icon="user-round">
    Store `id` as `user_id` plus `username`, `name`, `description`, `followers`,
    `following`, `verified`, and `verifiedType`.
  </Card>

  <Card title="Lookup key" icon="key-round">
    Join on the numeric user ID, which does not change. Use username lookup when the
    workflow starts from a handle.
  </Card>

  <Card title="Availability" icon="triangle-alert">
    Store `unavailable` and `unavailableReason` when returned. Retries,
    support triage, and CRM syncs can then distinguish missing accounts from unavailable
    profiles.
  </Card>

  <Card title="Next action" icon="route">
    Use the returned `id` for followers, following, timelines, media, DMs,
    follow checks, and monitor setup.
  </Card>
</CardGroup>

## Store a Twitter profile lookup

Keep the numeric X user ID as the stable key. Profile usernames, names, bios,
counts, verification, locations, links, and images can change between lookups.

| Profile column | Response field | CRM or warehouse rule |
| - | - | - |
| `x_user_id` | `id` | Use as the stable profile upsert and relationship key. |
| `x_username` | `username` | Store the current handle. Do not use it as the key. |
| `display_name` | `name` | Keep the public profile name observed during lookup. |
| `bio` | `description` | Store the profile bio when X returns it. |
| `follower_count` | `followers` | Keep the observed follower count with the lookup time. |
| `following_count` | `following` | Keep the observed following count with the lookup time. |
| `verified` | `verified` | Record the observed verification state. |
| `verified_type` | `verifiedType` | Distinguish returned business or government verification types. |
| `location` | `location` | Keep the public profile location when supplied. |
| `profile_url` | `url` | Keep the public website link from the profile. |
| `profile_image_url` | `profilePicture` | Use the returned image in profile previews and review queues. |
| `account_created_at` | `createdAt` | Keep the account creation timestamp when available. |
| `unavailable` | `unavailable` | Separate an unavailable profile from a successful active lookup. |
| `unavailable_reason` | `unavailableReason` | Handle suspended, deactivated, or otherwise unavailable profiles separately. |

| Next workflow | Stable input | Route |
| - | - | - |
| Follower export | `id` | `/x/users/{id}/followers` |
| Following export | `id` | `/x/users/{id}/following` |
| Profile timeline | `id` | `/x/users/{id}/tweets` |
| Profile replies | `id` | `/x/users/{id}/replies` |
| Profile media | `id` | `/x/users/{id}/media` |
| Profile highlights | `id` | `/x/users/{id}/highlights` |
| One follow relationship | Source and target usernames | `/x/followers/check` |
| Saved profile or audience job | Numeric profile ID in the selected tool input | `/extractions` |

## Path parameters

<ParamField path="id" type="string" required>
  User ID, username with or without `@`, or URL-encoded profile URL, such as
  `x.com/nasa`. See [path IDs](/api-reference/overview#path-ids).
</ParamField>

## Which user endpoint?

<CardGroup cols={2}>
  <Card title="User profile" icon="user-round">
    Use `GET /x/users/{id}` for one profile row by username or numeric user ID.
  </Card>

  <Card title="Search users" icon="search">
    Use [`GET /x/users/search`](/api-reference/x/search-users) when the workflow
    starts from a name, keyword, or partial handle.
  </Card>

  <Card title="Profile timeline" icon="list">
    Use [`GET /x/users/{id}/tweets`](/api-reference/x/user-tweets) for posts from
    one profile.
  </Card>

  <Card title="Followers" icon="users">
    Use [`GET /x/users/{id}/followers`](/api-reference/x/followers) when the next
    step needs audience rows.
  </Card>

  <Card title="Follow check" icon="user-check">
    Use [`GET /x/followers/check`](/api-reference/x/check-follower) when the
    workflow only needs one source-target relationship.
  </Card>

  <Card title="Saved exports" icon="file-spreadsheet">
    Use [`Create extraction`](/api-reference/extractions/create).
    Create saved CSV, JSON, or XLSX jobs. Export followers, following, timelines,
    media, or search.
  </Card>
</CardGroup>

## Headers

<ParamField header="x-api-key" type="string">
  Full account key. Sessions and OAuth also work.
</ParamField>

<ParamField header="Authorization" type="string">
  `Bearer xq_your_guest_key_here` authenticates `paid_reads` guest keys. Direct MPP uses the `Payment ...` credential. Get it from the `WWW-Authenticate: Payment` challenge.
</ParamField>

## Response

### 200 OK

<ResponseField name="id" type="string">
  User ID.
</ResponseField>

<ResponseField name="username" type="string">
  X username.
</ResponseField>

<ResponseField name="name" type="string">
  Display name.
</ResponseField>

<ResponseField name="description" type="string">
  Profile bio. Omitted if empty.
</ResponseField>

<ResponseField name="followers" type="number">
  Follower count. Omitted if unavailable.
</ResponseField>

<ResponseField name="following" type="number">
  Following count. Omitted if unavailable.
</ResponseField>

<ResponseField name="verified" type="boolean">
  Whether the user is verified. Omitted if unavailable.
</ResponseField>

<ResponseField name="profilePicture" type="string">
  Profile picture URL. Omitted if unavailable.
</ResponseField>

<ResponseField name="location" type="string">
  Profile location. Omitted if empty.
</ResponseField>

<ResponseField name="accountBasedIn" type="object | null">
  Country or region X shows for the account, with `value`, `level` & `observedAt`. X infers it from
  account access. It states no nationality or exact location. `null` when X shows none. Omitted when
  X withholds it.
</ResponseField>

<ResponseField name="accountBasedInUnavailable" type="boolean">
  `true` when X withheld `accountBasedIn` from this read. Retry later to get it. Omitted otherwise.
</ResponseField>

<ResponseField name="accountBasedInAccurate" type="boolean">
  `false` when X notes that `accountBasedIn` may be inaccurate. Omitted if unavailable.
</ResponseField>

<ResponseField name="connectedVia" type="string">
  How the account first connected to X, such as `United States App Store`. Omitted if unavailable.
</ResponseField>

<ResponseField name="connectedViaAccurate" type="boolean">
  `false` when X notes that the `connectedVia` country may be inaccurate. Omitted if unavailable.
</ResponseField>

<ResponseField name="usernameChanges" type="object">
  How often the account changed its username: `count` and, when there was a change, `lastChangedAt`.
  Omitted if unavailable.
</ResponseField>

<ResponseField name="birthdate" type="object">
  The parts of the birthday the account made public: `day`, `month`, and `year`. Omitted if
  unavailable.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 account creation timestamp. Omitted if unavailable.
</ResponseField>

<ResponseField name="statusesCount" type="number">
  Total number of tweets posted. Omitted if unavailable.
</ResponseField>

<ResponseField name="coverPicture" type="string">
  Cover or banner image URL. Omitted if unavailable.
</ResponseField>

<ResponseField name="mediaCount" type="number">
  Total number of media tweets posted. Omitted if unavailable.
</ResponseField>

<ResponseField name="url" type="string">
  Website URL from profile. Omitted if empty.
</ResponseField>

<ResponseField name="favouritesCount" type="number">
  Total number of tweets liked. Omitted if unavailable.
</ResponseField>

<ResponseField name="hasCustomTimelines" type="boolean">
  Whether the user has custom timelines (lists). Omitted if unavailable.
</ResponseField>

<ResponseField name="isTranslator" type="boolean">
  Whether the user is a Twitter translator. Omitted if unavailable.
</ResponseField>

<ResponseField name="withheldInCountries" type="string[]">
  Country codes where the account is withheld. Omitted if empty.
</ResponseField>

<ResponseField name="possiblySensitive" type="boolean">
  Whether X flags the account as possibly sensitive. Omitted if unavailable.
</ResponseField>

<ResponseField name="pinnedTweetIds" type="string[]">
  IDs of pinned tweets. Omitted if none.
</ResponseField>

<ResponseField name="isAutomated" type="boolean">
  Whether X marks the account as automated. Omitted if unavailable.
</ResponseField>

<ResponseField name="automatedBy" type="string">
  Username of the account operator if automated. Omitted if not automated.
</ResponseField>

<ResponseField name="unavailable" type="boolean">
  Whether the account is unavailable (suspended, deactivated). Omitted if available.
</ResponseField>

<ResponseField name="unavailableReason" type="string">
  Reason the account is unavailable. Omitted if available.
</ResponseField>

<ResponseField name="verifiedType" type="string">
  Verification type (for example `Business`, `Government`). Omitted if not verified or standard blue
  check.
</ResponseField>

<ResponseField name="profile_bio" type="object">
  Structured profile bio with entity annotations. Omitted if unavailable.
</ResponseField>

<ResponseField name="isBlueVerified" type="boolean">
  Whether the account has X Premium verification. Omitted if unavailable.
</ResponseField>

<ResponseField name="isVerified" type="boolean">
  Normalized verification status. Omitted if unavailable.
</ResponseField>

<ResponseField name="profileBannerUrl" type="string">
  Profile banner URL. Omitted if unavailable.
</ResponseField>

<ResponseField name="protected" type="boolean">
  Whether the account protects its posts. Omitted if unavailable.
</ResponseField>

<ResponseField name="communityRole" type="string">
  Role within a returned community context. Omitted outside community results.
</ResponseField>

<ResponseField name="listedCount" type="number">
  Public lists that include the profile. Omitted if unavailable.
</ResponseField>

<ResponseField name="fastFollowersCount" type="number">
  Followers X counts as fast followers. Omitted if unavailable.
</ResponseField>

<ResponseField name="normalFollowersCount" type="number">
  Followers minus fast followers. Omitted if unavailable.
</ResponseField>

<ResponseField name="subscribersCount" type="number">
  Accounts subscribed to the profile's paid Subscriptions. 0 when it has none. Omitted if
  unavailable.
</ResponseField>

<ResponseField name="defaultProfile" type="boolean">
  Whether the profile keeps X's default theme. Omitted if unavailable.
</ResponseField>

<ResponseField name="defaultProfileImage" type="boolean">
  Whether the profile keeps X's default avatar. Omitted if unavailable.
</ResponseField>

<ResponseField name="geoEnabled" type="boolean">
  Whether the profile may add a location to posts. Omitted if unavailable.
</ResponseField>

<ResponseField name="hasExtendedProfile" type="boolean">
  Whether the profile filled X's extended fields, such as a birth date. Omitted if unavailable.
</ResponseField>

<ResponseField name="isTranslationEnabled" type="boolean">
  Whether the account turned on X's translation of its posts. Omitted if unavailable.
</ResponseField>

<ResponseField name="advertiserAccountType" type="string">
  The account's X Ads type. `none` for an account without ads, or `promotable_user` for one that may
  run them. Omitted if unavailable.
</ResponseField>

<ResponseField name="advertiserAccountServiceLevels" type="string[]">
  X Ads services the account uses, such as `analytics`, `media_studio` or `smb`. Empty for an
  account without ads. Omitted if unavailable.
</ResponseField>

<ResponseField name="businessProfileState" type="string">
  Whether X treats the profile as a business profile. `none` or `enabled`. Omitted if unavailable.
</ResponseField>

<ResponseField name="verificationReason" type="object">
  X's `text` on why the profile is verified, with the `entities` that link parts of it. Omitted if
  unavailable.
</ResponseField>

```json theme={null}
{
  "id": "987654321",
  "username": "username",
  "name": "Xquik",
  "description": "X real-time data platform",
  "followers": 10000,
  "following": 500,
  "verified": true,
  "profilePicture": "https://pbs.twimg.com/profile_images/xquik/photo.jpg",
  "coverPicture": "https://pbs.twimg.com/profile_banners/xquik/cover.jpg",
  "location": "San Francisco",
  "url": "https://xquik.com",
  "createdAt": "2020-01-15T00:00:00.000Z",
  "statusesCount": 5000,
  "mediaCount": 120,
  "favouritesCount": 430,
  "isAutomated": false,
  "possiblySensitive": false,
  "hasCustomTimelines": false,
  "pinnedTweetIds": ["1234567890"]
}
```

### 400 Invalid user ID

```json theme={null}
{
  "error": "invalid_user_id",
  "message": "Send a user ID, @username or profile URL, such as x.com/nasa."
}
```

The path names no user. Send a user ID, username or profile URL.

### 401 Unauthenticated

```json theme={null}
{ "error": "unauthenticated" }
```

Missing or invalid API key. Check the `x-api-key` header value.

### 402 Payment required

Account keys get account options. Guest keys get guest top-up only.
Anonymous calls receive a direct MPP `WWW-Authenticate: Payment` challenge plus a guest wallet creation action.
No checkout starts automatically. Confirm any payment action.

### 404 User not found

```json theme={null}
{ "error": "user_not_found" }
```

X shows no profile for the user. The answer adds `reason`: `not_found`, or
`suspended` when X suspended the account. Check the username or choose another
account.

### 502 X API unavailable

```json theme={null}
{ "error": "x_api_unavailable" }
```

The read service returned an error. Retry after a short delay.

### 429 Rate limit exceeded

```json theme={null}
{ "error": "rate_limit_exceeded", "retryAfter": 60 }
```

You exceeded your tier rate limit. Wait for the `Retry-After` header before retrying.

### 424 Dependency failed

```json theme={null}
{ "error": "x_api_unavailable" }
```

The normalized v1 response contract can return 424 when the read service is unavailable.

<Note>
  **Next steps.** [Check Follower](/api-reference/x/check-follower) to verify follow relationships, or [Search Tweets](/api-reference/x/search-tweets) to find tweets from this user.
</Note>

<div className="related-api-links">
  <Accordion title="Related follower, list & community APIs" icon="link">
    * Profiles: [Search users](/api-reference/x/search-users) · [Search autocomplete](/api-reference/x/search-autocomplete) · [Get user](/api-reference/x/twitter-profile-lookup) · [Batch users](/api-reference/x/batch-users)
    * Followers: [Followers](/api-reference/x/followers) · [Following](/api-reference/x/following) · [Follower IDs](/api-reference/x/follower-ids) · [Following IDs](/api-reference/x/following-ids) · [Creator subscriptions](/api-reference/x/user-subscriptions) · [Affiliates](/api-reference/x/user-affiliates) · [Similar accounts](/api-reference/x/user-similar) · [Verified followers](/api-reference/x/verified-followers) · [Followers you know](/api-reference/x/followers-you-know) · [Check follower](/api-reference/x/check-follower)
    * Lists: [Search lists](/api-reference/x/search-lists) · [User lists](/api-reference/x/user-lists) · [List memberships](/api-reference/x/user-list-memberships) · [List members](/api-reference/x/list-members) · [List followers](/api-reference/x/list-followers)
    * Communities: [Find](/api-reference/x/community-find) · [Popular](/api-reference/x/community-popular) · [Topics](/api-reference/x/community-topics) · [Suggested](/api-reference/x/community-suggested) · [Details](/api-reference/x/community-info) · [Members](/api-reference/x/community-members) · [Moderators](/api-reference/x/community-moderators) · [Timeline](/api-reference/x/community-tweets) · [Media](/api-reference/x/community-media) · [Keyword search](/api-reference/x/community-search)
  </Accordion>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.