X Audience

Beta

Export the followers or following of any X (Twitter) account. The endpoint is cursor-paginated and metered per page — call it repeatedly, passing back the returned user_id and next_cursor, until next_cursor is null.

Note

X audience export is a paid feature — free or lapsed accounts receive a 403. Each page fetched is billed at your plan rate (Starter 5, Growth 3, Pro 2, Scale 1 credits); each page returns roughly 1–2k users.

Export an audience

POST/v1/x/audience

Export followers or following for an account, one metered page at a time.

json

{
  "handle": "@webclaw",
  "direction": "followers",
  "max_pages": 2
}

Parameters

Field	Type	Required	Description
`handle`	`string`	No	`@handle`, resolved once (unbilled). Provide `handle` or `user_id`.
`user_id`	`string`	No	Pre-resolved numeric id. Pass it back on later pages to skip re-resolving.
`direction`	`string`	No	`followers` (default) or `following`.
`cursor`	`string`	No	Opaque cursor from a previous response's `next_cursor`.
`max_pages`	`integer`	No	Pages to fetch this call (1–10). Default: 2. Each page is roughly 1–2k users.

Response

json

{
  "user_id": "44196397",
  "direction": "followers",
  "count": 2000,
  "users": [
    {
      "id": "1234567890",
      "screen_name": "example_user",
      "name": "Example User",
      "followers": 1523,
      "description": "Builder. Writing about the web.",
      "url": "https://example.com"
    }
  ],
  "next_cursor": "1770000000000000000|-1",
  "pages_fetched": 2,
  "credits_charged": 2
}

Field	Type	Description
`user_id`	`string`	The resolved numeric id of the account. Pass it back on later pages.
`direction`	`string`	`followers` or `following`.
`count`	`integer`	Number of users returned in this response.
`users`	`object[]`	The exported users. See the fields below.
`next_cursor`	`string \| null`	Cursor for the next call. `null` means the audience is fully walked.
`pages_fetched`	`integer`	Pages fetched on this call.
`credits_charged`	`integer`	Credits billed for this call (your plan rate per page: Starter 5, Growth 3, Pro 2, Scale 1).

User object

Field	Type	Description
`id`	`string`	Numeric account id.
`screen_name`	`string`	The @handle, without the leading @.
`name`	`string`	Display name.
`followers`	`integer`	Follower count.
`description`	`string`	Profile bio.
`url`	`string`	Profile website link, if any.

Paging a full audience

Resolve the handle once, then chain calls with the returned user_id and next_cursor until next_cursor comes back null.

bash

# First call — resolve the handle and fetch the first pages
curl -X POST https://api.webclaw.io/v1/x/audience \
  -H "Authorization: Bearer wc_..." \
  -H "Content-Type: application/json" \
  -d '{"handle": "@webclaw", "direction": "followers"}'

# Next call — reuse user_id and pass next_cursor
curl -X POST https://api.webclaw.io/v1/x/audience \
  -H "Authorization: Bearer wc_..." \
  -H "Content-Type: application/json" \
  -d '{"user_id": "44196397", "direction": "followers", "cursor": "1770000000000000000|-1"}'

SDK examples

Python

python

from webclaw import Webclaw

client = Webclaw(api_key="wc_...")

# Walk a full follower list
cursor = None
user_id = None
while True:
    page = client.x.audience(
        handle="@webclaw" if user_id is None else None,
        user_id=user_id,
        direction="followers",
        cursor=cursor,
    )
    user_id = page.user_id
    for user in page.users:
        print(user.screen_name)
    cursor = page.next_cursor
    if cursor is None:
        break

TypeScript

typescript

import Webclaw from "@webclaw/sdk";

const client = new Webclaw({ apiKey: "wc_..." });

// Walk a full follower list
let cursor: string | null = null;
let userId: string | undefined;
do {
  const page = await client.x.audience({
    handle: userId ? undefined : "@webclaw",
    userId,
    direction: "followers",
    cursor: cursor ?? undefined,
  });
  userId = page.userId;
  for (const user of page.users) console.log(user.screenName);
  cursor = page.nextCursor;
} while (cursor !== null);

cURL