Dataclawd X/Twitter Data Collector

A reliable Actor that collects X/Twitter social data through the Dataclawd API — a managed social-data API with API-key authentication, usage reporting and prepaid credits. This Actor is a thin client: it calls the endpoint you choose (or maps a friendly task to the right endpoint automatically), follows pagination cursors automatically, extracts each item, and writes one row per item into the default Dataset (each successful row is also the pay-per-event billing event).

It covers users, tweets, search & trends, followers/following, lists, communities, notifications and DM inboxes — 57 read/data endpoints in total (see the endpoint list).

Powered by Dataclawd API · Not affiliated with X Corp. or Twitter.

Quick start

1. Open the Actor's Input tab.
2. Pick a task (collection task), e.g. userTweets (a user's tweets) — the endpoint is selected automatically.
3. Fill the endpoint's parameters in params, e.g.:

   { "userId": "44196397" }
   

4. Optionally set maxItems / maxPages to control volume, or add multiple objects to targets to batch-collect.
5. Click Run and open the Dataset tab when it finishes — every collected item is one row with the raw JSON in the data field.

Input

Field	Type	Default	Description
task	enum	—	Recommended. Collection intent, auto-maps to an endpoint (see Tasks below). Leave empty only if you set endpoint explicitly.
endpoint	enum	auto	Advanced. auto = resolve from task; or set an explicit endpoint to override.
params	object	—	Endpoint-specific request parameters as JSON, e.g. {"screenName":"elonmusk"}. Applied to every target.
targets	array of object	(empty)	Batch mode: each element is a param set (overrides params), collected one after another.
authToken	string	(empty)	X web-login auth_token cookie. Required for account-scoped endpoints (notifications, DMs).
ct0	string	(empty)	X web-login ct0 cookie (some account-scoped endpoints).
proxyUrl	string	(empty)	Proxy used by Dataclawd's server when fetching X.
httpMethod	enum	POST	POST or GET (both are defined in the Dataclawd OpenAPI).
maxItems	integer	100	Stop after this many items in total (max 100 000).
maxPages	integer	10	Max pages per target (max 100).
startCursor	string	(empty)	Resume from a previous cursor instead of page 1.
itemsPath	string	(empty)	Dot-path to the item list in the response, e.g. data.items. Leave empty for auto-detection (largest array).
nextCursorPath	string	(empty)	Dot-path to the next-page cursor. Leave empty for auto-detection (bottom/next/cursor/after…).
paginationParam	enum	auto	Query param used for paging: auto (cursor), after, or none (no paging).

Supported endpoints

Tasks

Pick a task and the Actor selects the endpoint for you. Fill the endpoint's parameters in params (or targets for batch).

Task	Endpoint	Required params
userProfile User profile	userByScreenNameV2	screenName
userTweets User tweets	userTweetsV2	userId
userMedia User media	userMedia	userId
userLikes User likes	userLikeV2	userId
tweetDetail Tweet detail	tweetSimple	id
search Search tweets	search	words
trending Global trends	trending	—
followers User followers	followersListV2	userId
following User following	followingsListV2	userId
listTweets List tweets	listLatestTweetsTimelineV2	listId
communityTweets Community tweets	CommunitiesTweetsTimelineV2	communityId
notifications Notifications	notificationsAll	needs authToken
dmInbox DM inbox	getDMSListV2	needs authToken

Group	Endpoints
Users	userByScreenNameV2, uerByIdRestIdV2, usersByIdRestIds, usernameChanges, highlightsV2, UserArticlesTweets
Tweets	tweetSimple, tweetTimeline, tweetResultsByRestIds, userTweetsV2, userTimeline, userMedia, userLikeV2, userTweetReply, favoritesList
Tweet interactions	favoritersV2, retweetersV2, retweetersIds, quotesV2
Search & trends	search, searchBox, trends, trending, explore, news, sports, entertainment
Followers / following	followersListV2, followingsListV2, followersIds, followingsIds, friendshipsShow, blueVerifiedFollowersV2
Lists	listByRestIdV2, listByUserIdOrScreenName, listFollowersByListIdV2, listLatestTweetsTimelineV2, listMembersByListIdV2, listSearchTimeline
Communities	CommunitiesSearchV2, CommunitiesTweetsTimelineV2, CommunitiesMemberV2, CommunitiesTimelineV2, CommunityQueryV2, CommunitiesFetchOneQuery, TopicListV2, getCommunitiesByScreenName
Space (optional auth)	AudioSpaceById
Notifications (auth)	notificationsAll, notificationsMentions, notificationsVerified, notificationsV2
DM inbox (auth)	getDMSListV2, getUpdateDMSV2, getDMSInitIdV2, getDMS, getCanSendDMS

Each endpoint's required parameters are listed in the endpoint dropdown description and in docs/dataclawd-api-reference.md of the project repository.

Output (Dataset — one row per collected item)

Field	Description
platform	Always twitter.
endpoint	The endpoint that produced this row.
status	completed (data collected) or failed (request-level failure).
target	Human-readable target summary, e.g. userId=44196397.
page	Page number this item came from (1-based).
itemIndex	Sequential index within the run (1-based).
cursor	Cursor used to fetch that page (-1 = first page).
data	The collected item — the raw JSON returned by Dataclawd (tweet, user, etc.).
errorStage	Where a failure happened: connect_failed / server_error / auth_error / rate_limited / request_error / parse_error / empty_result.
errorCode	HTTP status code (if any), e.g. 429.
error	Error message on failed rows.

Run status & status message

While running, the Actor's status message is updated periodically (Collecting … → Collecting …: wrote n items → Done: …). The run succeeds (SUCCEEDED) as soon as at least one item is collected. If every target fails or returns nothing, the run ends FAILED with an explanatory message. Billing happens only for completed rows.

How to verify the results

1. Run status: the run is SUCCEEDED when at least one item was written; the status message shows live progress.
2. Per-item state: open the run's Dataset — every collected item has status=completed with the raw JSON in data; failed rows explain why (errorStage / errorCode / error).
3. Spot-check against the API: re-run one target in the Dataclawd API Console and compare with the row's data.
4. Billing: only completed rows carry the item-collected pay-per-event charge.

Developer note: for automated checks (run status, row schema, optional Dataclawd API replay), use python3 tools/verify_output.py --run <RUN_ID> [--api].

Pricing

Pay-per-event (PPE): one item-collected event per successfully collected item. Failed rows do not carry this event.

Publishing note: define an item-collected event with your price in the Actor's Monetization tab. The platform's built-in synthetic event apify-default-dataset-item is charged automatically per default-dataset item when PPE is enabled; set its price to 0 if you don't want a per-item base fee.

Configuration (publisher)

The following environment variables are configured on the Actor's version settings and are not visible to end users:

• DATACLAWD_API_HOST — Dataclawd API base URL (e.g. https://api.dataclawd.example).
• DATACLAWD_API_KEY — Dataclawd API key (sent as X-API-Key).

Disclaimer

This Actor is not affiliated with, endorsed by, or sponsored by X Corp. or Twitter. Collect only data you are authorized to collect, and comply with X's Terms of Service, the Dataclawd service terms, and applicable law.

---