What is the X Followers List API?

X Followers List API is a programmatic interface for collecting public account records for people who follow one or more submitted X usernames.

Which username formats are accepted?

Pass a nonempty usernames array. Each value may include or omit a leading @; surrounding whitespace is trimmed and duplicate handles are removed case-insensitively before provider collection.

How does results_limit work?

The value applies separately to each username, defaults to 200, and must be a multiple of 200 between 200 and 2,000. It is a ceiling, so public availability and pagination can produce fewer results.

What does each public result contain?

The current task serializer returns the account ID, canonical profile URL, author ID, username and name, visible profile metrics, the normalized account-creation time when available, and the saved-record creation time.

How are duplicate follower accounts handled?

Repeated provider rows are deduplicated by account ID, and the same account is saved once across the entire task even if it follows more than one submitted username.

How is the X Followers List API priced?

Each uniquely saved result costs 0.5 SocQ credits. The task is precharged from results_limit multiplied by the submitted username count, then unused credits are refunded after successful settlement; an empty result costs zero credits.

X Followers List API: Public Follower Data

X Followers List

An X follower list is the set of public account records returned for people following a submitted username at collection time. It supports audience research and list enrichment while remaining subject to public availability, provider pagination, and task-level deduplication.

Features

Multi-account follower collectionSubmit one or more public X usernames in a single task, with or without a leading @.
Per-username result controlsRequest 200 to 2,000 follower records per username in increments of 200, with 200 used by default.
Normalized public account recordsReceive account IDs, canonical profile URLs, author identity, visible profile counters, and normalized timestamps through the public task result.
Asynchronous delivery optionsPoll task results with an opaque cursor until collection finishes, then continue through all available result pages.

Parameters

Parameters	Required	Description
`usernames`	Required	Required list of public X usernames. Values may include or omit a leading @; whitespace is trimmed and duplicate usernames are removed case-insensitively before collection.
`results_limit`	Optional	Maximum results to collect for each username. Defaults to 200 and accepts multiples of 200 from 200 through 2,000.

How to Use

Start a follower collection task, wait for completion, then page through the saved public account records.

Prepare one or more public X usernames; a leading @ is optional.
POST usernames and a valid results_limit to /v1/x/followers-list, then retain the returned task_id.
Poll /v1/tasks/{task_id} until the task reaches succeeded or failed.
After success, read data.results.items and pass next_cursor back to the task endpoint while has_more is true.

curl -X POST "https://api.socq.ai/v1/x/followers-list" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@X"],"results_limit":200}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

Build audience research samples: Collect public follower accounts for selected X profiles and analyze visible account scale across the returned sample.
Enrich known account directories: Add canonical X profile URLs, display identities, account IDs, and visible counters to downstream account records.
Create repeatable follower snapshots: Run the same bounded collection over time and retain task timestamps to compare saved public account sets.

Pro Tips

Deduplicate usernames before submission because the temporary credit estimate uses the submitted array length, while collection normalizes duplicate handles.
Treat results_limit as a per-username ceiling, not a promise that every account will return the requested number of public records.
Use each result id as the stable key; the same follower encountered under multiple submitted usernames is saved once within a task.
Keep provider pagination separate from result retrieval: only the opaque next_cursor from /v1/tasks/{task_id} is public.
Handle empty and partial results without failing the workflow because unavailable accounts, access restrictions, or an exhausted source can shorten a collection.

Use these APIs when you need a different type of public X data.

Twitter Tweet Scraper API — Retrieve public post text, authors, engagement, media, hashtags, mentions, and conversation relationships from x.com or twitter.com status URLs.
Twitter Profile Scraper API — Retrieve public account identity, biographies, avatars, cover images, account status, and visible audience statistics by username.
Twitter User Tweets Scraper API — Collect recent public posts, authors, media, hashtags, mentions, and engagement by username with replies excluded.
Twitter Search API — Find public posts by search expression with latest or top ordering and a configurable result limit.
X Following List API — Collect profiles followed by public X accounts, including identity, biographies, account signals, visible counters, and source usernames.
X Post Quotes API — Collect public quote posts for known status URLs with commentary, authors, engagement, media, timestamps, and source-post context.
X Post Replies API — Collect public replies from X post URLs with selectable ordering, reply text, authors, visible engagement, media, and parent-post context.
X Post Retweeters API — Collect a task-level unique set of normalized public profiles for accounts that reposted known X or Twitter status URLs.
X Trends API — Collect current public X trend snapshots for known numeric WOEIDs with source rank, query, description, and location context.

Combine X data with public data from other supported social platforms.