Search Tweets
Search tweets using Twitter/X advanced search syntax. Supports Latest and Top result types. Returns tweet data including text, author, engagement metrics, and media. Paginated with cursor. Ideal for: monitoring keywords, tracking conversations, content discovery, sentiment analysis. Profile picture is opt-in via `includeProfilePicture`.
Catalog action Social
Search tweets using Twitter/X advanced search syntax. Supports Latest and Top result types. Returns tweet data including text, author, engagement metrics, and media. Paginated with cursor. Ideal for: monitoring keywords, tracking conversations, content discovery, sentiment analysis. Profile picture is opt-in via includeProfilePicture.
At a Glance
| Field | Value |
|---|---|
| Action ID | x-search-tweets |
| Category | Social |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | social, twitter, x, tweets, search, read |
Payload Schema
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query using Twitter advanced search syntax (e.g., 'from:elonmusk', '#crypto', 'bitcoin OR ethereum') |
queryType | string | No | Result type: 'Latest' for chronological order, 'Top' for most engaged tweets. Default: 'Latest' |
cursor | string | null | No | Pagination cursor from a previous response to retrieve the next page of results. 'null' is treated the same as omitting the field (start from the first page). When the previous response had reached the end, 'nextCursor' is a sentinel value; passing that sentinel back returns an empty result so a pagination loop stops instead of restarting from the first page. |
includeProfilePicture | boolean | No | Include the author's profile picture URL in each tweet. Off by default because the URL plus inlined base64 can bloat responses past the 100KB downstream limit. When false (default), 'authorProfilePicture' is returned as null. |
Result Schema
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | 'success' or 'error' |
tweets | array | Yes | Array of tweet objects matching the search query |
totalResults | number | Yes | Number of tweets returned in this response |
hasNextPage | boolean | Yes | Whether more results are available via pagination |
nextCursor | string | null | No | Cursor to pass as 'cursor' in the next request for the following page. When there are no more results this is a sentinel value (not null); passing it back yields an empty result, so a pagination loop terminates instead of restarting from the first page. Use 'hasNextPage' to decide whether to continue. |
error | string | No | Error message if status is 'error' |
Examples
json{ "type": "x-search-tweets", "payload": { "query": "status:open" }, "children": []}
bashcurl -X POST "https://api.b3os.org/v1/actions/x-search-tweets/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "query": "status:open" }}'
Payload fields can use workflow expressions such as {{$trigger.body.amount}}, {{$nodes.fetch.result.price}}, and {{$props.asset}} when the value should come from a trigger, prior node, or reusable workflow prop.