# Twitter on boxd

> Twitter, Inc. was an American social media company based in San Francisco, California, which operated and was named for named for its flagship social media network prior to its rebrand as X.

- Page: https://boxd.sh/integrations/twitter/
- CLI: `run twitter` (79 commands, 13 marked common)
- SDK: `import { twitter } from "@boxd/run"`; every parameter and response type is at `@boxd/run/twitter`
- Triggers: none
- Connect: `run auth twitter` (Sign in with Twitter), or https://app.boxd.sh/integrations/detail/twitter
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth twitter      # once: prints a link to connect your account
run twitter           # list its commands
run twitter user-lookup-me --help
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, twitter } from "@boxd/run";

every("1 hour", async () => {
  const result = await twitter.userLookupMe({});
  console.log(result);
});
```

Run it with `run twitter.run.ts`. Twitter has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run twitter <command> --help` lists the optional ones. "common" marks what `run twitter` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-list-member` | `twitter.addListMember()` | `--id` `--user-id` | 0 | Adds a user to a specified Twitter List; the list must be owned by the authenticated user |
| `add-post-to-bookmarks` | `twitter.addPostToBookmarks()` | `--id` `--tweet-id` | 0 | Adds a specified, existing, and accessible Tweet to a user's bookmarks, with success indicated by the 'bookmarked' field in the response |
| `append-media-upload` | `twitter.appendMediaUpload()` | `--id` `--media` `--segment-index` | 0 | Append data chunk to an ongoing media upload session on X/Twitter |
| `bookmarks-by-user` | `twitter.bookmarksByUser()` | — | 10 | Retrieves Tweets bookmarked by the authenticated user, where the provided User ID must match the authenticated user's ID |
| `create-activity-subscription` | `twitter.createActivitySubscription()` | `--event-type` `--filter` | 2 | Create a subscription for an X activity event |
| `create-compliance-job` | `twitter.createComplianceJob()` | `--type` | 2 | Creates a new compliance job to check the status of Tweet or user IDs; upload IDs as a plain text file (one ID per line) to the `upload_url` received in the response |
| `create-dm-conversation` | `twitter.createDmConversation()` | `--conversation-type` `--message` `--participant-ids` | 0 | Creates a new group Direct Message (DM) conversation on Twitter |
| `create-list` ·common | `twitter.createList()` | `--name` | 2 | Creates a new, empty List on X (formerly Twitter), for which the provided name must be unique for the authenticated user; accounts are added separately |
| `creation-of-post` ·common | `twitter.creationOfPost()` | — | 15 | Creates a Tweet on Twitter; `text` is required unless `card_uri`, `media_media_ids`, `poll_options`, or `quote_tweet_id` is provided |
| `delete-dm` | `twitter.deleteDm()` | `--event-id` | 0 | Permanently deletes a specific Twitter Direct Message (DM) event using its `event_id` if the authenticated user sent it; this action is irreversible and does not delete entire conversations |
| `delete-list` ·common | `twitter.deleteList()` | `--id` | 0 | Permanently deletes a specified Twitter List using its ID, which must be owned by the authenticated user; this action is irreversible and the list must already exist |
| `follow-list` | `twitter.followList()` | `--id` `--list-id` | 0 | Allows the authenticated user (`id`) to follow a specific Twitter List (`list_id`) they are permitted to access, subscribing them to the list's timeline; this does not automatically follow individual… |
| `follow-user` ·common | `twitter.followUser()` | `--target-user-id` | 1 | Allows an authenticated user (path `id`) to follow another user (`target_user_id`), which results in a pending request if the target user's tweets are protected |
| `followers-by-user-id` | `twitter.followersByUserId()` | `--id` | 5 | Retrieves a list of users who follow a specified public Twitter user ID |
| `following-by-user-id` | `twitter.followingByUserId()` | `--id` | 5 | Retrieves users followed by a specific Twitter user, allowing pagination and customization of returned user and tweet data fields via expansions |
| `full-archive-search` | `twitter.fullArchiveSearch()` | `--query` | 13 | Searches the full archive of public Tweets from March 2006 onwards; use 'start_time' and 'end_time' together for a defined time window |
| `get-blocked-users` ·common | `twitter.getBlockedUsers()` | `--id` | 5 | Retrieves the authenticated user's own block list |
| `get-compliance-job` | `twitter.getComplianceJob()` | `--id` | 1 | Retrieves status, download/upload URLs, and other details for an existing Twitter compliance job specified by its unique ID |
| `get-compliance-jobs` | `twitter.getComplianceJobs()` | `--type` | 2 | Returns a list of recent compliance jobs, filtered by type (tweets or users) and optionally by status |
| `get-dm-conversation-events` | `twitter.getDmConversationEvents()` | `--participant-id` | 8 | Fetches Direct Message (DM) events for a one-on-one conversation with a specified participant ID, ordered chronologically newest to oldest; does not support group DMs |
| `get-dm-event` | `twitter.getDmEvent()` | `--event-id` | 5 | Fetches a specific Direct Message (DM) event by its unique ID, allowing optional expansion of related data like users or tweets; ensure the `event_id` refers to an existing DM event accessible to the… |
| `get-list` | `twitter.getList()` | `--id` | 3 | Returns metadata for a specific Twitter List, identified by its ID; does not return list members but can expand the owner's User object via the `expansions` parameter |
| `get-list-followers` | `twitter.getListFollowers()` | `--id` | 5 | Fetches a list of users who follow a specific Twitter List, identified by its ID; ensure the authenticated user has access if the list is private |
| `get-list-members` | `twitter.getListMembers()` | `--id` | 5 | Fetches members of a specific Twitter List, identified by its unique ID |
| `get-media-upload-status` | `twitter.getMediaUploadStatus()` | `--media-id` | 0 | Get the processing status of uploaded media (videos/GIFs) on X/Twitter |
| `get-muted-users` | `twitter.getMutedUsers()` | `--id` | 5 | Returns user objects muted by the X user identified by the `id` path parameter |
| `get-openapi-spec` | `twitter.getOpenapiSpec()` | — | 0 | Fetches the OpenAPI specification (JSON) for Twitter's API v2, used to programmatically understand the API's structure for developing client libraries or tools |
| `get-post-analytics` ·common | `twitter.getPostAnalytics()` | `--end-time` `--ids` `--start-time` | 2 | Retrieve analytics data for specified Posts within a defined time range |
| `get-post-retweeters-action` | `twitter.getPostRetweetersAction()` | `--id` | 5 | Retrieves users who publicly retweeted a specified public Post ID, excluding Quote Tweets and retweets from private accounts |
| `get-post-retweets` | `twitter.getPostRetweets()` | `--id` | 8 | Retrieves Tweets that Retweeted a specified public or authenticated-user-accessible Tweet ID, optionally customizing the response with fields and expansions |
| `get-post-usage` | `twitter.getPostUsage()` | — | 2 | Fetches Tweet usage statistics for a Project (e.g., consumption, caps, daily breakdowns for Project & Client Apps) to monitor API limits; data can be retrieved for 1 to 90 days |
| `get-recent-dm-events` | `twitter.getRecentDmEvents()` | — | 8 | Returns recent Direct Message events for the authenticated user, such as new messages or changes in conversation participants |
| `get-space-by-id` | `twitter.getSpaceById()` | `--id` | 4 | Retrieves details for a Twitter Space by its ID, allowing for customization and expansion of related data, provided the Space ID is valid and accessible |
| `get-space-posts` | `twitter.getSpacePosts()` | `--id` | 7 | Retrieves Tweets that were shared/posted during a Twitter Space broadcast |
| `get-space-ticket-buyers` | `twitter.getSpaceTicketBuyers()` | `--id` | 5 | Retrieves a list of users who purchased tickets for a specific, valid, and ticketed Twitter Space |
| `get-spaces-by-creators` | `twitter.getSpacesByCreators()` | `--user-ids` | 4 | Retrieves Twitter Spaces created by a list of specified User IDs, with options to customize returned data fields |
| `get-spaces-by-ids` | `twitter.getSpacesByIds()` | `--ids` | 4 | Fetches detailed information for one or more Twitter Spaces (live, scheduled, or ended) by their unique IDs; at least one Space ID must be provided |
| `get-user-by-id` | `twitter.getUserById()` | `--id` | 3 | Retrieves detailed public information for a Twitter user by their ID, optionally expanding related data (e.g., pinned tweets) and specifying particular user or tweet fields to return |
| `get-user-followed-lists` | `twitter.getUserFollowedLists()` | `--id` | 5 | Returns metadata (not Tweets) for lists a specific Twitter user follows, optionally including expanded owner details |
| `get-user-list-memberships` | `twitter.getUserListMemberships()` | `--id` | 5 | Retrieves all Twitter Lists a specified user is a member of, including public Lists and private Lists the authenticated user is authorized to view |
| `get-user-owned-lists` | `twitter.getUserOwnedLists()` | `--id` | 5 | Call this action to retrieve Lists created (owned) by a specific Twitter user, not Lists they follow or are subscribed to |
| `get-user-pinned-lists` | `twitter.getUserPinnedLists()` | `--id` | 3 | Retrieves the Lists a specific, existing Twitter user has pinned to their profile to highlight them |
| `get-users-by-ids` | `twitter.getUsersByIds()` | `--ids` | 3 | Retrieves detailed information for specified X (formerly Twitter) user IDs, optionally customizing returned fields and expanding related entities |
| `hide-replies` | `twitter.hideReplies()` | `--hidden` `--tweet-id` | 0 | Hides or unhides an existing reply Tweet |
| `initialize-media-upload` ·common | `twitter.initializeMediaUpload()` | `--media-type` `--total-bytes` | 3 | Initialize a media upload session for X/Twitter |
| `list-post-likers` | `twitter.listPostLikers()` | `--id` | 5 | Retrieves users who have liked the Post (Tweet) identified by the provided ID |
| `list-posts-timeline-by-list-id` | `twitter.listPostsTimelineByListId()` | `--id` | 8 | Fetches the most recent Tweets posted by members of a specified Twitter List |
| `mute-user` | `twitter.muteUser()` | `--target-user-id` | 1 | Mutes a target user on behalf of an authenticated user, preventing the target's Tweets and Retweets from appearing in the authenticated user's home timeline without notifying the target |
| `pin-list` | `twitter.pinList()` | `--id` `--list-id` | 0 | Pins a specified List to the authenticated user's profile, provided the List exists, the user has access rights, and the pin limit (typically 5 Lists) is not exceeded |
| `post-delete-by-post-id` ·common | `twitter.postDeleteByPostId()` | `--id` | 0 | Irreversibly deletes a specific Tweet by its ID; the Tweet may persist in third-party caches after deletion |
| `post-lookup-by-post-id` | `twitter.postLookupByPostId()` | `--id` | 6 | Fetches comprehensive details for a single Tweet by its unique ID, provided the Tweet exists and is accessible |
| `post-lookup-by-post-ids` | `twitter.postLookupByPostIds()` | `--ids` | 6 | Retrieves detailed information for one or more Posts (Tweets) identified by their unique IDs, allowing selection of specific fields and expansions |
| `recent-search` ·common | `twitter.recentSearch()` | `--query` | 14 | Searches Tweets from the last 7 days matching a query (using X's search syntax), ideal for real-time analysis, trend monitoring, or retrieving posts from specific users (e.g., `from:username`)… |
| `remove-list-member` | `twitter.removeListMember()` | `--id` `--user-id` | 0 | Removes a user from a Twitter List; the response `is_member` field will be `false` if removal was successful or the user was not a member, and the updated list of members is not returned |
| `remove-post-from-bookmarks` | `twitter.removePostFromBookmarks()` | `--tweet-id` | 1 | Removes a Tweet, specified by `tweet_id`, from the authenticated user's bookmarks; the Tweet must have been previously bookmarked by the user for the action to have an effect |
| `retrieve-dm-conversation-events` | `twitter.retrieveDmConversationEvents()` | `--id` | 8 | Retrieves Direct Message (DM) events for a specific conversation ID on Twitter, useful for analyzing messages and participant activities |
| `retrieve-posts-that-quote-post` | `twitter.retrievePostsThatQuotePost()` | `--id` | 9 | Retrieves Tweets that quote a specified Tweet, requiring a valid Tweet ID |
| `returns-post-objects-liked-by-provided-user-id` | `twitter.returnsPostObjectsLikedByProvidedUserId()` | `--id` | 8 | Retrieves Tweets liked by a specified Twitter user, provided their liked tweets are public or accessible |
| `retweet-post` | `twitter.retweetPost()` | `--tweet-id` | 0 | Retweets a Tweet for the authenticated user |
| `search-full-archive-counts` | `twitter.searchFullArchiveCounts()` | `--query` | 8 | Returns a count of Tweets from the full archive that match a specified query, aggregated by day, hour, or minute; `start_time` must be before `end_time` if both are provided, and… |
| `search-recent-counts` | `twitter.searchRecentCounts()` | `--query` | 8 | Retrieves the count of Tweets matching a specified search query within the last 7 days, aggregated by 'minute', 'hour', or 'day' |
| `search-spaces` | `twitter.searchSpaces()` | `--query` | 6 | Searches for Twitter Spaces by a textual query, optionally filtering by state (live, scheduled, all) to discover audio conversations |
| `send-dm-to-conversation` | `twitter.sendDmToConversation()` | `--dm-conversation-id` | 2 | Sends a message, with optional text and/or media attachments (using pre-uploaded `media_id`s), to a specified Twitter Direct Message conversation |
| `send-new-message-to-user` | `twitter.sendNewMessageToUser()` | `--participant-id` | 2 | Sends a new Direct Message with text and/or media (media_id for attachments must be pre-uploaded) to a specified Twitter user; this creates a new DM and does not modify existing messages |
| `stream-post-labels` | `twitter.streamPostLabels()` | — | 3 | Stream real-time Tweet label events (apply/remove) |
| `unfollow-list` | `twitter.unfollowList()` | `--id` `--list-id` | 0 | Enables a user (via `id`) to unfollow a specific Twitter List (via `list_id`), which removes its tweets from their timeline and stops related notifications; the action reports `following: false` on… |
| `unfollow-user` ·common | `twitter.unfollowUser()` | `--target-user-id` | 1 | Allows the authenticated user to unfollow an existing Twitter user (`target_user_id`), which removes the follow relationship |
| `unlike-post` | `twitter.unlikePost()` | `--id` `--tweet-id` | 0 | Allows an authenticated user (`id`) to remove their like from a specific post (`tweet_id`); the action is idempotent and completes successfully even if the post was not liked |
| `unmute-user` | `twitter.unmuteUser()` | `--target-user-id` | 0 | Unmutes a target user for the authenticated user, allowing them to see Tweets and notifications from the target user again |
| `unpin-list` | `twitter.unpinList()` | `--list-id` | 1 | Unpins a List (specified by list_id) from the authenticated user's profile |
| `unretweet-post` | `twitter.unretweetPost()` | `--source-tweet-id` | 1 | Removes a user's retweet of a specified Post, if the user had previously retweeted it |
| `update-list` | `twitter.updateList()` | `--id` | 3 | Updates an existing Twitter List's name, description, or privacy status, requiring the List ID and at least one mutable property |
| `upload-large-media` | `twitter.uploadLargeMedia()` | `--media` | 3 | Use this to upload a single media file to X/Twitter |
| `upload-media` ·common | `twitter.uploadMedia()` | `--media` | 4 | Upload media (images only) to X/Twitter using the v2 API |
| `user-home-timeline-by-user-id` | `twitter.userHomeTimelineByUserId()` | — | 14 | Retrieves the home timeline (reverse chronological feed) for the authenticated Twitter user |
| `user-like-post` | `twitter.userLikePost()` | `--id` `--tweet-id` | 0 | Allows the authenticated user to like a specific, accessible Tweet, provided neither user has blocked the other and the authenticated user is not restricted from liking |
| `user-lookup-by-username` | `twitter.userLookupByUsername()` | `--username` | 3 | Fetches public profile information for a valid and existing Twitter user by their username, optionally expanding related data like pinned Tweets; results may be limited for protected profiles not… |
| `user-lookup-by-usernames` ·common | `twitter.userLookupByUsernames()` | `--usernames` | 3 | Retrieves detailed information for 1 to 100 Twitter users by their usernames (each 1-15 alphanumeric characters/underscores), allowing customizable user/tweet fields and expansion of related data… |
| `user-lookup-me` ·common | `twitter.userLookupMe()` | — | 3 | Returns profile information for the currently authenticated X user, customizable via request fields |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.