> ## 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 user search, lookup & audience counts

> Search Twitter or X users by name or username. Return matching profiles, biographies, follower counts, verification status, and pagination. 1 credit per result.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-search-users-200">
      ```json theme={null}
      {
        "users": [],
        "has_next_page": false,
        "next_cursor": ""
      }
      ```
    </Tab>

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

    <Tab title="401" id="response-x-search-users-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required."
      }
      ```
    </Tab>

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

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

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

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

    <Tab title="503" id="response-x-search-users-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>

<Note>
  Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, Xquik returns fewer results. If zero paid results are affordable, it returns `402 insufficient_credits`.
</Note>

<Callout icon="coins" color="#5c3327">
  **1 credit per result returned** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

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

  ```javascript Node.js theme={null}
  const query = "xquik";
  const params = new URLSearchParams({ q: query });
  const response = await fetch(`https://xquik.com/api/v1/x/users/search?${params}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const nextCursor = data.has_next_page ? data.next_cursor : null;
  const searchRows = data.users.map((user, index) => ({
    search_query: query,
    result_rank: index + 1,
    user_id: user.id,
    username: user.username,
    display_name: user.name,
    bio: user.description ?? null,
    follower_count: user.followers ?? null,
    following_count: user.following ?? null,
    verified: user.verified ?? false,
    profile_image_url: user.profilePicture ?? null,
    next_cursor: nextCursor,
  }));
  ```

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

  query = "xquik"
  response = requests.get(
      "https://xquik.com/api/v1/x/users/search",
      params={"q": query},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  next_cursor = data["next_cursor"] if data["has_next_page"] else None
  search_rows = [
      {
          "search_query": query,
          "result_rank": index + 1,
          "user_id": user["id"],
          "username": user["username"],
          "display_name": user["name"],
          "bio": user.get("description"),
          "follower_count": user.get("followers"),
          "following_count": user.get("following"),
          "verified": user.get("verified", False),
          "profile_image_url": user.get("profilePicture"),
          "next_cursor": next_cursor,
      }
      for index, user in enumerate(data["users"])
  ]
  ```
</CodeGroup>

The Node.js and Python snippets build search-result rows. They do not
print full profile pages. Store `searchRows` or `search_rows` with
`nextCursor` or `next_cursor` before requesting the next page.

## Direct user search handoff

Use `GET /x/users/search` when a CRM, enrichment, creator discovery, support,
or agent workflow has a name, brand, or handle fragment. It returns matching X
profiles. Use [Get User](/api-reference/x/twitter-profile-lookup) when you have one exact ID
or username. Use [Get Users (Batch)](/api-reference/x/batch-users) when you
already have numeric user IDs.

Store `search_query`, `result_rank`, `user_id`, `username`, `display_name`,
profile metrics, verification state, `profile_image_url`, `has_next_page`, and
`next_cursor`. Treat `next_cursor` as opaque and pass it back as `cursor` only
when `has_next_page` is true. Zero affordable results return
`402 insufficient_credits`.

## Resolve the intended X profile

Use user search when a workflow starts with a name or username fragment.
Inspect several candidates before choosing a numeric user ID. Similar profile
names can represent unrelated people or organizations.

Show reviewers:

* Username and profile name.
* Biography and location.
* Verification state.
* Follower and following counts.
* Profile image and numeric user ID.

Store the chosen user ID for later requests. Usernames can change. Numeric IDs
are the safer key for followers, following, timelines, and profile
lookups.

An empty search result is not an API failure. Separate no
matches from invalid authentication, rate limits, and insufficient credits.

Do not use a result row number as identity. Ranking can change between
searches. Always pass the selected user ID into the next workflow.

## Query parameters

<ParamField query="q" type="string" required>
  Search query string.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response. Omit for the first page.
</ParamField>

<ParamField query="pageSize" type="integer">
  Profiles per page. Range: `20-200`. Defaults to `20`.
</ParamField>

<ParamField query="enrichProfiles" type="boolean" default="false">
  Set `true` to add each row's full profile, as `GET /x/users/{id}` returns it.
  Pages take several seconds longer. The price per row stays the same.
</ParamField>

### User result filters

These filters apply before billing. Selective filters can return fewer rows.

<ParamField query="minFollowers" type="integer">
  Require this minimum follower count. Filtering happens before billing.
</ParamField>

<ParamField query="maxFollowers" type="integer">
  Allow this maximum follower count. Missing counts pass this filter.
</ParamField>

<ParamField query="minFollowing" type="integer">
  Require this minimum following count.
</ParamField>

<ParamField query="maxFollowing" type="integer">
  Allow this maximum following count. Missing counts pass this filter.
</ParamField>

<ParamField query="minStatuses" type="integer">
  Require this minimum post count.
</ParamField>

<ParamField query="maxStatuses" type="integer">
  Allow this maximum post count. Missing counts pass this filter.
</ParamField>

<ParamField query="minAccountAgeDays" type="integer">
  Require this minimum account age in days.
</ParamField>

<ParamField query="verifiedOnly" type="boolean">
  When `true`, only return verified profiles.
</ParamField>

<ParamField query="verifiedType" type="string">
  Match the exact verification type.
</ParamField>

<ParamField query="hasWebsite" type="boolean">
  When `true`, require a profile website.
</ParamField>

<ParamField query="hasLocation" type="boolean">
  When `true`, require a profile location.
</ParamField>

<ParamField query="bioContains" type="string">
  Require every comma-separated or line-separated bio term.
</ParamField>

<ParamField query="locationContains" type="string">
  Require this text in the profile location.
</ParamField>

<ParamField query="usernameContains" type="string">
  Require this text in the username.
</ParamField>

## 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` for `paid_reads`.
</ParamField>

## Response

### 200 OK

With `enrichProfiles=true`, each row carries the full profile. The
`x-xquik-profile-enrichment` header then counts the rows that have it, as in
`enriched=180; requested=200`. A row without it keeps its list fields.

<ResponseField name="users" type="object[]">
  Array of matching user profiles.
  **User object fields.**

  <ResponseField name="id" type="string">
    X 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.
  </ResponseField>

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

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

  <ResponseField name="verified" type="boolean">
    Verified status.
  </ResponseField>

  <ResponseField name="profilePicture" type="string">
    Profile image URL.
  </ResponseField>

  <ResponseField name="location" type="string">
    Profile location.
  </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. Present with
    `enrichProfiles=true`, unless X withholds it.
  </ResponseField>

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

  <ResponseField name="createdAt" type="string">
    Account creation date (ISO 8601).
  </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. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="isTranslator" type="boolean">
    Whether the user is an X 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. 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 the requested community context. Omitted outside community results.
  </ResponseField>
</ResponseField>

<ResponseField name="has_next_page" type="boolean">Whether more results are available.</ResponseField>
<ResponseField name="next_cursor" type="string">Cursor for the next page.</ResponseField>

```json theme={null}
{
  "users": [
    {
      "id": "987654321",
      "username": "username",
      "name": "Xquik",
      "followers": 10000,
      "verified": true,
      "description": "All-in-one X automation platform"
    }
  ],
  "has_next_page": true,
  "next_cursor": "DAACCgACGE..."
}
```

### 400 Missing query

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

### 401 Unauthenticated

Anonymous requests get `WWW-Authenticate: Bearer` and a guest wallet checkout action. This is not a Payment challenge.

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

### 402 Payment required

Account keys get account options. Guest keys get guest top-up only.
No checkout starts automatically. Confirm any payment action.

### 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.** [Get User](/api-reference/x/twitter-profile-lookup) to fetch full details, or [Search Tweets](/api-reference/x/search-tweets) to find tweets by query.
</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.