> ## 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 audience discovery with follower exports
> Find Twitter audience segments with user search, follower exports, following pages, verified followers, batch enrichment, and CSV or JSON handoff steps.
For the complete documentation index, see llms.txt.
Use this workflow when a sales, research, community, or marketing job needs a
scored audience list. The job can start with a topic, brand, creator, or
competitor account. Key every row by X user ID. Exports, CRMs, agents, and
warehouse loads can then deduplicate later.
This workflow produces public profile and relationship evidence. It does not
create an X Ads custom audience. It also does not return private emails,
purchase behavior, age, or gender.
## Define the audience question
Start with one decision your audience list must support. Examples include
finding relevant creators, qualifying public profiles, or comparing follower
communities. Keep the question beside every exported row.
Choose a source that matches that decision:
* User search finds public profiles matching a name, handle, or topic.
* Followers show who follows a selected public account.
* Following shows which accounts a selected profile follows.
* Verified followers isolate returned profiles with X verification.
* Tweet search confirms public conversation around a selected topic.
Do not treat every follower as a qualified prospect. A follower relationship
proves one public connection. It does not prove role, budget, intent, or
permission to contact that person.
## Pick the discovery path
Use `GET /api/v1/x/users/search?q={query}` or `people_search` to find
candidate profiles by name, handle, or topic.
Use `follower_explorer` or `GET /api/v1/x/users/{id}/followers` to collect
people who already follow one seed account.
Use `following_explorer` or `GET /api/v1/x/users/{id}/following` to collect
accounts one seed profile follows.
Use `verified_follower_explorer` or
`GET /api/v1/x/users/{id}/verified-followers` when you score verified accounts
separately.
## Seed accounts
Start with a query when you do not already have exact handles. Store the search
query, rank, user ID, username, follower count, verification state, and cursor.
```bash theme={null}
curl "https://xquik.com/api/v1/x/users/search?q=ai%20founder" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
If the seed list comes from another system, enrich up to 100 numeric user IDs
per request before expanding the list.
```bash theme={null}
curl "https://xquik.com/api/v1/x/users/batch?ids=44196397,987654321" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
Prefer numeric X user IDs as stable keys. Usernames and display names can
change. Store the latest username as an attribute, not the CRM primary key.
Keep `seed_query`, `seed_user_id`, `seed_username`, and `seed_rank` together.
That evidence explains why each follower or following row entered the audience.
## Expand the audience
Use extraction jobs when the output needs estimate, retry, audit, and file
download handoff. Use direct JSON pages when the app needs the freshest page
now.
`POST /api/v1/extractions/estimate`, then `POST /api/v1/extractions` with
`toolType: "follower_explorer"`.
Use `toolType: "following_explorer"` with `targetUsername` and optional
`resultsLimit`.
Use `toolType: "people_search"` with `searchQuery` for reusable profile
search exports.
Use `toolType: "verified_follower_explorer"` for a reusable verified
follower export.
```bash theme={null}
curl -X POST https://xquik.com/api/v1/extractions \
-H "x-api-key: xq_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"toolType": "follower_explorer",
"targetUsername": "username",
"resultsLimit": 5000
}' | jq
```
Export the completed job when the audience list is ready for a CRM, sheet, or
warehouse.
```bash theme={null}
curl "https://xquik.com/api/v1/extractions/77777/export?format=csv" \
-H "x-api-key: xq_YOUR_KEY_HERE" \
-o target-audience.csv
```
## Direct JSON pages
Use direct pages when the app owns the loop and checkpoint state.
```bash theme={null}
curl "https://xquik.com/api/v1/x/users/username/followers?pageSize=200" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
```bash theme={null}
curl "https://xquik.com/api/v1/x/users/username/following?pageSize=200" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
```bash theme={null}
curl "https://xquik.com/api/v1/x/users/44196397/verified-followers" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
Store `has_next_page` and `next_cursor` with the seed account and route. Pass
`next_cursor` back as `cursor` only when `has_next_page` is true.
Save a checkpoint after every completed page. Include the route, seed user ID,
input cursor, next cursor, page size, and collection time. Retry from the last
saved next cursor after a worker restart.
Stop when `has_next_page` is false or `next_cursor` is empty. Also stop when a
cursor repeats. Never share one cursor between followers and following routes.
## Combine audience sources
Union sources when broad discovery matters. Intersect sources when stronger
relationship evidence matters. Always join on numeric X user ID.
Useful source combinations include:
* Followers of several relevant creators reveal shared audience members.
* Following lists reveal accounts your seed profiles chose.
* User search plus followers validates a topic match and relationship.
* Verified followers plus tweet search validates verification and activity.
* Batch user enrichment refreshes profile fields before CRM upserts.
Store one evidence row per source relationship. Build one normalized candidate
row after collection. This keeps multiple reasons for the same candidate.
```json theme={null}
{
"candidate_user_id": "987654321",
"source_count": 3,
"sources": ["followers:44196397", "followers:123456789", "search:ai founder"],
"matched_queries": ["ai founder"],
"matching_tweet_ids": ["1893704267862470862"]
}
```
## Score rows
Create one normalized row per candidate before enrichment or outreach.
```json theme={null}
{
"audience_id": "ai-founder-q2",
"seed_source": "GET /api/v1/x/users/search",
"seed_query": "ai founder",
"seed_user_id": "44196397",
"candidate_user_id": "987654321",
"candidate_username": "username",
"display_name": "Xquik",
"follower_count": 2400,
"following_count": 430,
"verified": true,
"verified_type": "Business",
"profile_image_url": "https://pbs.twimg.com/profile_images/xquik.jpg",
"bio": "X automation platform",
"location": "San Francisco",
"source_route": "GET /api/v1/x/users/{id}/followers",
"page_cursor": null,
"matched_at": "2026-05-24T19:51:00.000Z"
}
```
Score with fields Xquik already returns: follower count, following count,
verification state, verification type, bio, location, profile image, account
creation date, media count, website URL, and protected-account state.
Use written, task-specific qualification rules. Store every rule result
beside the final decision. Avoid one unexplained audience score.
Count distinct seed accounts, source routes, and matched search queries.
Evaluate returned bio, location, verification, and public profile counts.
Keep matching tweet IDs, creation times, replies, reposts, and likes.
Store `qualified`, `qualification_reasons`, and the ruleset version.
Do not invent missing profile attributes. A blank location is unknown, not a
failed location match. A missing verification type is not a personal account
classification. A large follower count does not prove topical relevance.
## Validate active conversation
Use tweet search when a candidate segment must be active around a topic before
it enters a campaign, CRM list, or agent queue.
```bash theme={null}
curl "https://xquik.com/api/v1/x/tweets/search?q=ai%20founder%20min_faves%3A10&verifiedOnly=true" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
Store tweet IDs separately from audience rows. Do not overwrite the candidate
profile row with the latest matching tweet.
Use returned tweet fields for public conversation evidence. Store tweet text,
author ID, creation time, reply count, repost count, like count, and quote
count when returned. Keep the search query and cursor beside each page.
Separate profile qualification from tweet qualification. A profile can match
your audience even when no recent tweet matches. A matching tweet can also come
from a profile that fails your audience rules.
## Build a Twitter lead generation handoff
Treat the exported file as a public-profile research list. Apply your consent,
privacy, and outreach rules before contacting anyone. Xquik does not supply
private email addresses or private messages through this workflow.
Use numeric X user ID for CRM upserts. Keep these concrete columns:
* `x_user_id`
* `x_username`
* `display_name`
* `bio`
* `location`
* `follower_count`
* `following_count`
* `verified`
* `verified_type`
* `source_count`
* `source_seed_ids`
* `matched_queries`
* `matching_tweet_ids`
* `qualified`
* `qualification_reasons`
* `collected_at`
* `ruleset_version`
Keep public profile facts separate from your internal sales fields. Do not
overwrite `bio`, `location`, or follower counts with CRM notes. Refresh public
fields by X user ID and keep prior collection timestamps.
## Measure Twitter audience insights
Calculate insights only from collected public profiles and tweets. Report the
sample size, collection time, seed accounts, query, and missing-field counts.
Useful measurements include:
* Shared followers across selected seed accounts
* Followers versus following source counts
* Verified and unverified profile counts
* Returned profile locations without inferred geography
* Bio terms found in returned descriptions
* Recent matching authors and tweet counts
* Reply, repost, like, and quote totals for matching tweets
These measurements describe the collected sample. They do not represent every
X user or private demographic attribute. Keep that limitation in dashboards,
AI summaries, and client reports.
## Handle audience collection failures
* `400`: Correct the query, user ID, username, or page parameter.
* `401`: Replace the missing or invalid credential.
* `402`: Top up credits before resuming the saved cursor.
* `404`: Verify the seed account or requested profile still resolves.
* `424`: Retry the temporary read-service dependency failure.
* `429`: Wait for `Retry-After` before requesting another page.
* `502`: Retry the temporary read-service failure later.
Retry `424`, `429`, and `502` with capped backoff. Do not restart from page one.
Resume from the last committed cursor. Do not retry `400`, `401`, `402`, or
`404` without changing the request or account state.
## Twitter audience discovery questions
### How do I find my target audience on Twitter?
Start with topic searches or relevant seed accounts. Expand their followers or
following lists. Then qualify profiles with returned fields and matching tweets.
### How do I analyze a competitor's Twitter followers?
Export that public account's followers. Keep the competitor's numeric X user ID
as the seed. Deduplicate candidates by their own numeric X user IDs.
### Can I export Twitter followers to CSV?
Yes. Run a `follower_explorer` extraction, wait for completion, then export CSV.
Use direct JSON pages when your application owns pagination and checkpoints.
### What is the difference between followers and following?
Followers chose to follow the seed account. Following lists accounts the seed
profile chose. Keep these relationship directions separate in every row.
### Can Xquik return Twitter audience demographics?
No. This workflow returns documented public profile and tweet fields. Do not
infer private age, gender, email, purchase behavior, or other demographics.
### How do I build a Twitter lead list?
Collect public profiles, keep source evidence, and apply explicit
qualification rules. Export only the fields your CRM needs. Apply consent and
outreach requirements outside this collection workflow.
### How do I prevent duplicate audience profiles?
Use numeric X user ID as the unique key. Store usernames as mutable profile
fields. Keep every source relationship in separate evidence rows.
### How do I keep audience exports current?
Refresh profile fields by numeric X user ID. Keep `collected_at` on every
snapshot. Never overwrite historical evidence without retaining its timestamp.
## Cost and retry notes
Estimate extraction jobs before running large follower, following, verified
follower, or people search exports.
Xquik meters direct JSON pages by returned user or tweet rows. Low credit
balances can return smaller pages or `402 insufficient_credits`.
Treat cursors as opaque route checkpoints. They are not stable profile IDs.
## Next steps
Find seed profiles by topic, name, or handle.
Build CSV, JSON, or XLSX follower files for CRM and warehouse handoff.
Page accounts followed by one seed profile.
Enrich up to 100 numeric user IDs in one request.
* 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)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.