Skip to main content
GET
Twitter following API, profile export & cursors

When to read outbound relationships

Use this route for accounts the selected user follows. Use followers for inbound relationships. Use verified followers when you need only verified inbound followers.
1 credit per result returned · All plans from $0.00012/credit
Get following returns the accounts one X profile follows by username or numeric user ID. The endpoint is GET /api/v1/x/users/{id}/following.
Omit mode for automatic maximum coverage. Xquik combines available views within a short request window. It keeps the existing response shape. Pass next_cursor back unchanged as cursor. Keep the same endpoint, target, query, and filters.
Existing unprefixed cursors keep their legacy behavior. after, limit, and pageSize aliases also keep working. Billing still counts only returned rows. Use mode=standard only to force legacy single-view pagination. A page can be empty or underfilled. Continue while has_next_page is true. Stop only after the response reports has_next_page=false. First-page requests do not support Idempotency-Key retries. Repeating a cursorless request starts a separate extraction. Results returned by that extraction incur their normal charges. Save each response before requesting its next page. You cannot replay earlier or terminal responses after their cursors become unavailable. If automatic coverage is busy, an initial request returns a standard data page. Live coverage cursors remain atomic. Concurrent use returns 409 coverage_cursor_unavailable with exact Retry-After seconds. Wait, then retry the same cursor once. Repeated busy responses never authorize restarting with another cursor. Finished, expired, superseded, or identity-mismatched cursors return 410 coverage_cursor_gone. The response omits Retry-After. Restart without a cursor. Keep received results. Deduplicate restarted results by id. Malformed cursors return 400 invalid_coverage_cursor. Restart without them.
The Node.js and Python snippets write JSON Lines audience rows, not raw following pages. Store each mapped row and the latest next_cursor in your sync job. It can then resume from the last completed page. For high-volume following pulls, deduplicate profiles by id. Continue through empty pages while the cursor advances. Stop with a partial-result status when next_cursor is missing or repeats.

Direct following handoff

Use GET /x/users/{id}/following when a CRM, warehouse, audience, or agent workflow needs one paginated JSON page of accounts followed by a user now. The endpoint accepts a username or numeric user ID. It returns followed account profile rows with cursor fields. Use following_explorer when you need an estimated job, saved extraction, or CSV, JSON, or XLSX file export.

Following rows

Store users[] as the followed account profile rows returned on this page.

Stable upserts

Store users[].id as x_user_id for CRM, warehouse, audience, and agent deduplication.

Readable labels

Store users[].username and users[].name for handles, labels, segments, and review queues.

Profile enrichment

Store users[].description, location, url, profilePicture, and coverPicture when returned.

Next page

Store has_next_page and next_cursor, then pass next_cursor back as cursor only when has_next_page is true.

Page size

Automatic pages accept 20 to 300. Standard pages accept 20 to 200.
Direct following calls cost 1 credit per user returned. Low credit balances can return fewer users than a full page. Zero affordable results return 402 insufficient_credits.

Track Twitter following changes

Create complete following snapshots for the selected profile. Keep its numeric user ID and collection time with every row. Compare snapshots by followed user ID. New IDs represent newly observed outbound follows. Missing IDs represent removals only when both snapshots completed. Keep the current username, profile name, biography, verification state, and follower counts for review. Do not use usernames as the comparison key. Store every cursor page before advancing. Mark interrupted, repeated-cursor, or credit-limited runs as partial. Never calculate following changes from a partial snapshot.

Path parameters

string
required
User ID, username with or without @, or URL-encoded profile URL, such as x.com/nasa. See path IDs.

Query parameters

string
Pass next_cursor back unchanged. New Xquik cursors resume automatic coverage. Existing unprefixed cursors keep legacy behavior.
string
Optional compatibility override. Omit it for automatic maximum coverage. Use standard for legacy single-view pagination. Use coverage for a one-shot diagnostic response without cursor pagination.
string
Legacy cursor alias. Use cursor. When both are present, cursor wins.
number
Automatic pages accept 20 through 300. Standard pages accept 20 through 200. The default is 200. Credits can reduce the returned row count.
number
With mode=coverage, set a one-shot cap from 1 through 10000. Otherwise, this is a legacy page size alias. pageSize wins.
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. Later pages can leave it out, & next_cursor still works.

Which following endpoint?

One user's following

Use GET /x/users/{id}/following for the accounts one profile follows.

One user's followers

Use GET /x/users/{id}/followers for the accounts that follow that profile.

Verified followers

Use GET /x/users/{id}/verified-followers when you only need verified followers of the profile.

Saved exports

Use following_explorer for a saved following extraction with CSV, JSON, or XLSX download handoff.

User result filters

These filters apply before billing. Selective filters can return fewer rows.
integer
Require this minimum follower count. Filtering happens before billing.
integer
Allow this maximum follower count. Missing counts pass this filter.
integer
Require this minimum following count.
integer
Allow this maximum following count. Missing counts pass this filter.
integer
Require this minimum post count.
integer
Allow this maximum post count. Missing counts pass this filter.
integer
Require this minimum account age in days.
boolean
When true, only return verified profiles.
string
Match the exact verification type.
boolean
When true, require a profile website.
boolean
When true, require a profile location.
string
Require every comma-separated or line-separated bio term.
string
Require this text in the profile location.
string
Require this text in the username.

Headers

string
Full account key. Sessions and OAuth also work.
string
Bearer xq_your_guest_key_here for paid_reads.

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.
object[]
Array of user profiles being followed. User object fields.
string
X user ID.
string
X username.
string
Display name.
string
Profile bio. Omitted if empty.
number
Follower count.
number
Following count.
boolean
Whether the user is verified.
string
Profile picture URL.
string
Profile location. Omitted if empty.
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.
boolean
true when X withheld accountBasedIn from this row. Retry later to get it. Omitted otherwise.
string
ISO 8601 account creation timestamp.
number
Total number of tweets posted. Omitted if unavailable.
string
Cover or banner image URL. Omitted if unavailable.
number
Total number of media tweets posted. Omitted if unavailable.
string
Website URL from profile. Omitted if empty.
number
Total number of tweets liked. Omitted if unavailable.
boolean
Whether the user has custom timelines. Omitted if unavailable.
boolean
Whether the user is an X translator. Omitted if unavailable.
string[]
Country codes where the account is withheld. Omitted if empty.
boolean
Whether X flags the account as possibly sensitive. Omitted if unavailable.
string[]
IDs of pinned tweets. Omitted if none.
boolean
Whether X marks the account as automated. Omitted if unavailable.
string
Username of the account operator if automated. Omitted if not automated.
boolean
Whether the account is unavailable. Omitted if available.
string
Reason the account is unavailable. Omitted if available.
string
Verification type (for example Business, Government). Omitted if not verified or standard blue check.
object
Structured profile bio with entity annotations. Omitted if unavailable.
boolean
Whether the account has X Premium verification. Omitted if unavailable.
boolean
Normalized verification status. Omitted if unavailable.
string
Profile banner URL. Omitted if unavailable.
boolean
Whether the account protects its posts. Omitted if unavailable.
string
Role within the requested community context. Omitted outside community results.
boolean
Whether more results are available.
string
Cursor for the next page.

400 Invalid user ID

404 User not found

401 Unauthenticated

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

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

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

429 Rate limit exceeded

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

424 Dependency failed

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