Skip to content

twarc2

Collect data from the Twitter V2 API.

Usage:

twarc2 [OPTIONS] COMMAND [ARGS]...

Options:

  --consumer-key TEXT         Twitter app consumer key (aka "App Key")
  --consumer-secret TEXT      Twitter app consumer secret (aka "App Secret")
  --access-token TEXT         Twitter app access token for user
                              authentication.
  --access-token-secret TEXT  Twitter app access token secret for user
                              authentication.
  --bearer-token TEXT         Twitter app access bearer token.
  --app-auth / --user-auth    Use application authentication or user
                              authentication. Some rate limits are higher with
                              user authentication, but not all endpoints are
                              supported.  [default: app-auth]
  --log TEXT
  --verbose
  --metadata / --no-metadata  Include/don't include metadata about when and
                              how data was collected.  [default: metadata]
  --config FILE               Read configuration from FILE.
  --help                      Show this message and exit.

configure

Set up your Twitter app keys.

Usage:

twarc2 configure [OPTIONS]

Options:

  --help  Show this message and exit.

conversation

Retrieve a conversation thread using the tweet id.

Usage:

twarc2 conversation [OPTIONS] TWEET_ID [OUTFILE]

Options:

  --archive  Search the full archive (requires Academic Research track)
  --help     Show this message and exit.

conversations

Fetch the full conversation threads that the input tweets are a part of. Alternatively the input can be a line oriented file of conversation ids.

Usage:

twarc2 conversations [OPTIONS] [INFILE] [OUTFILE]

Options:

  --limit INTEGER               Maximum number of tweets to return
  --conversation-limit INTEGER  Maximum number of tweets to return per-
                                conversation
  --archive                     Use the Academic Research project track access
                                to the full archive
  --help                        Show this message and exit.

flatten

"Flatten" tweets, or move expansions inline with tweet objects and ensure that each line of output is a single tweet.

Usage:

twarc2 flatten [OPTIONS] [INFILE] [OUTFILE]

Options:

  --help  Show this message and exit.

followers

Get the followers for a given user.

Usage:

twarc2 followers [OPTIONS] USER [OUTFILE]

Options:

  --limit INTEGER  Maximum number of followers to save
  --help           Show this message and exit.

following

Get the users who are following a given user.

Usage:

twarc2 following [OPTIONS] USER [OUTFILE]

Options:

  --limit INTEGER  Maximum number of friends to save
  --help           Show this message and exit.

hydrate

Hydrate tweet ids.

Usage:

twarc2 hydrate [OPTIONS] [INFILE] [OUTFILE]

Options:

  --help  Show this message and exit.

mentions

Retrieve the most recent tweets mentioning the given user.

Usage:

twarc2 mentions [OPTIONS] USER_ID [OUTFILE]

Options:

  --since-id INTEGER              Match tweets sent after tweet id
  --until-id INTEGER              Match tweets sent prior to tweet id
  --start-time [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]
                                  Match tweets created after time (ISO
                                  8601/RFC 3339), e.g.  2021-01-01T12:31:04
  --end-time [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]
                                  Match tweets sent before time (ISO 8601/RFC
                                  3339)
  --help                          Show this message and exit.

sample

Fetch tweets from the sample stream.

Usage:

twarc2 sample [OPTIONS] [OUTFILE]

Options:

  --limit INTEGER  Maximum number of tweets to save
  --help           Show this message and exit.

Search for tweets.

Usage:

twarc2 search [OPTIONS] QUERY [OUTFILE]

Options:

  --since-id INTEGER              Match tweets sent after tweet id
  --until-id INTEGER              Match tweets sent prior to tweet id
  --start-time [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]
                                  Match tweets created after UTC time (ISO
                                  8601/RFC 3339), e.g.  2021-01-01T12:31:04
  --end-time [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]
                                  Match tweets sent before UTC time (ISO
                                  8601/RFC 3339)
  --archive                       Search the full archive (requires Academic
                                  Research track)
  --limit INTEGER                 Maximum number of tweets to save
  --max-results INTEGER           Maximum number of tweets per API response
  --help                          Show this message and exit.

stream

Fetch tweets from the live stream.

Usage:

twarc2 stream [OPTIONS] [OUTFILE]

Options:

  --limit INTEGER  Maximum number of tweets to return
  --help           Show this message and exit.

stream-rules

List, add and delete rules for your stream.

Usage:

twarc2 stream-rules [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

add

Create a new stream rule to match a value. Rules can be grouped with optional tags.

Usage:

twarc2 stream-rules add [OPTIONS] VALUE

Options:

  --tag TEXT  a tag to help identify the rule
  --help      Show this message and exit.

delete

Delete the stream rule that matches a given value.

Usage:

twarc2 stream-rules delete [OPTIONS] VALUE

Options:

  --help  Show this message and exit.

delete-all

Delete all stream rules!

Usage:

twarc2 stream-rules delete-all [OPTIONS]

Options:

  --help  Show this message and exit.

list

List all the active stream rules.

Usage:

twarc2 stream-rules list [OPTIONS]

Options:

  --help  Show this message and exit.

timeline

Retrieve recent tweets for the given user.

Usage:

twarc2 timeline [OPTIONS] USER_ID [OUTFILE]

Options:

  --limit INTEGER                 Maximum number of tweets to return
  --since-id INTEGER              Match tweets sent after tweet id
  --until-id INTEGER              Match tweets sent prior to tweet id
  --exclude-retweets              Exclude retweets from timeline
  --exclude-replies               Exclude replies from timeline
  --start-time [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]
                                  Match tweets created after time (ISO
                                  8601/RFC 3339), e.g.  2021-01-01T12:31:04
  --end-time [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]
                                  Match tweets sent before time (ISO 8601/RFC
                                  3339)
  --use-search                    Use the search/all API endpoint which is not
                                  limited to the last 3200 tweets, but
                                  requires Academic Product Track access.
  --help                          Show this message and exit.

timelines

Fetch the timelines of every user in an input source of tweets. If the input is a line oriented text file of user ids or usernames that will be used instead.

Usage:

twarc2 timelines [OPTIONS] [INFILE] [OUTFILE]

Options:

  --limit INTEGER           Maximum number of tweets to return
  --timeline-limit INTEGER  Maximum number of tweets to return per-timeline
  --use-search              Use the search/all API endpoint which is not
                            limited to the last 3200 tweets, but requires
                            Academic Product Track access.
  --exclude-retweets        Exclude retweets from timeline
  --exclude-replies         Exclude replies from timeline
  --help                    Show this message and exit.

tweet

Look up a tweet using its tweet id or URL.

Usage:

twarc2 tweet [OPTIONS] TWEET_ID [OUTFILE]

Options:

  --pretty  Pretty print the JSON
  --help    Show this message and exit.

users

Get data for user ids or usernames.

Usage:

twarc2 users [OPTIONS] [INFILE] [OUTFILE]

Options:

  --usernames
  --help       Show this message and exit.

version

Return the version of twarc that is installed.

Usage:

twarc2 version [OPTIONS]

Options:

  --help  Show this message and exit.