> ## 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.
# Search users
> Search for X users by name or username and return matching profiles with pagination
For the complete documentation index, see llms.txt.
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`.
**1 credit per result returned** ยท [All plans](https://xquik.com/#pricing) from \$0.00012/credit
```bash cURL theme={null}
curl "https://xquik.com/api/v1/x/users/search?q=xquik" \
-H "x-api-key: xq_YOUR_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_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_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"])
]
```
The Node.js and Python snippets shape durable search-result rows instead of
printing full profile pages. Persist `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 and needs matching X
profiles. Use [Get User](/api-reference/x/get-user) 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`.
## Query parameters
Search query string.
Pagination cursor from a previous response. Omit for the first page.
## Headers
Your API key. Session cookie authentication is also supported.
## Response
Array of matching user profiles.
X user ID.
X username.
Display name.
Profile bio.
Follower count.
Following count.
Verified status.
Profile image URL.
Profile location.
Account creation date (ISO 8601).
Total number of tweets posted. Omitted if unavailable.
Cover/banner image URL. Omitted if unavailable.
Total number of media tweets posted. Omitted if unavailable.
Whether the user accepts direct messages. Omitted if unavailable.
Website URL from profile. Omitted if empty.
Total number of tweets liked. Omitted if unavailable.
Whether the user has custom timelines. Omitted if unavailable.
Whether the user is an X translator. Omitted if unavailable.
Country codes where the account is withheld. Omitted if empty.
Whether the account is flagged as possibly sensitive. Omitted if unavailable.
IDs of pinned tweets. Omitted if none.
Whether the account is marked as automated. Omitted if unavailable.
Username of the account operator if automated. Omitted if not automated.
Whether the account is unavailable. Omitted if available.
Reason the account is unavailable. Omitted if available.
Verification type (e.g. `Business`, `Government`). Omitted if not verified or standard blue check.
Structured profile bio with entity annotations. Omitted if unavailable.
Whether more results are available.
Cursor for the next page.
```json theme={null}
{
"users": [
{
"id": "987654321",
"username": "xquikcom",
"name": "Xquik",
"followers": 10000,
"verified": true,
"description": "All-in-one X automation platform"
}
],
"has_next_page": true,
"next_cursor": "DAACCgACGE..."
}
```
```json theme={null}
{ "error": "missing_query" }
```
```json theme={null}
{ "error": "unauthenticated" }
```
```json theme={null}
{ "error": "no_subscription" }
```
No active subscription or insufficient credits. Possible error values: `no_subscription`, `subscription_inactive`, `no_credits`, `insufficient_credits`.
```json theme={null}
{ "error": "x_api_unavailable" }
```
The read service returned an error. Retry after a short delay.
```json theme={null}
{ "error": "rate_limit_exceeded", "retryAfter": 60 }
```
Your tier rate limit was exceeded. Wait for the `Retry-After` header before retrying.
```json theme={null}
{ "error": "x_api_unavailable" }
```
The normalized v1 response contract can return 424 when the read service is unavailable.
**Next steps:** [Get User](/api-reference/x/get-user) to fetch full details, or [Search Tweets](/api-reference/x/search-tweets) to find tweets by query.