= twitter_search
:type: input
:status: experimental
:categories: ["Services","Social"]



////
     THIS FILE IS AUTOGENERATED!

     To make changes, edit the corresponding source file under:

     https://github.com/redpanda-data/connect/tree/main/internal/impl/<provider>.

     And:

     https://github.com/redpanda-data/connect/tree/main/cmd/tools/docs_gen/templates/plugin.adoc.tmpl
////

// © 2024 Redpanda Data Inc.


component_type_dropdown::[]


Consumes tweets matching a given search using the Twitter recent search V2 API.


[tabs]
======
Common::
+
--

```yml
# Common config fields, showing default values
input:
  label: ""
  twitter_search:
    query: "" # No default (required)
    tweet_fields: []
    poll_period: 1m
    backfill_period: 5m
    cache: "" # No default (required)
    api_key: "" # No default (required)
    api_secret: "" # No default (required)
```

--
Advanced::
+
--

```yml
# All config fields, showing default values
input:
  label: ""
  twitter_search:
    query: "" # No default (required)
    tweet_fields: []
    poll_period: 1m
    backfill_period: 5m
    cache: "" # No default (required)
    cache_key: last_tweet_id
    rate_limit: ""
    api_key: "" # No default (required)
    api_secret: "" # No default (required)
```

--
======

Continuously polls the https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-recent[Twitter recent search V2 API^] for tweets that match a given search query.

Each tweet received is emitted as a JSON object message, with a field `id` and `text` by default. Extra fields https://developer.twitter.com/en/docs/twitter-api/fields[can be obtained from the search API^] when listed with the `tweet_fields` field.

In order to paginate requests that are made the ID of the latest received tweet is stored in a xref:components:caches/about.adoc[cache resource], which is then used by subsequent requests to ensure only tweets after it are consumed. It is recommended that the cache you use is persistent so that Benthos can resume searches at the correct place on a restart.

Authentication is done using OAuth 2.0 credentials which can be generated within the https://developer.twitter.com[Twitter developer portal^].


== Fields

=== `query`

A search expression to use.


*Type*: `string`


=== `tweet_fields`

An optional list of additional fields to obtain for each tweet, by default only the fields `id` and `text` are returned. For more info refer to the https://developer.twitter.com/en/docs/twitter-api/fields[twitter API docs^].


*Type*: `array`

*Default*: `[]`

=== `poll_period`

The length of time (as a duration string) to wait between each search request. This field can be set empty, in which case requests are made at the limit set by the rate limit. This field also supports cron expressions.


*Type*: `string`

*Default*: `"1m"`

=== `backfill_period`

A duration string indicating the maximum age of tweets to acquire when starting a search.


*Type*: `string`

*Default*: `"5m"`

=== `cache`

A cache resource to use for request pagination.


*Type*: `string`


=== `cache_key`

The key identifier used when storing the ID of the last tweet received.


*Type*: `string`

*Default*: `"last_tweet_id"`

=== `rate_limit`

An optional rate limit resource to restrict API requests with.


*Type*: `string`

*Default*: `""`

=== `api_key`

An API key for OAuth 2.0 authentication. It is recommended that you populate this field using xref:configuration:interpolation.adoc[environment variables].


*Type*: `string`


=== `api_secret`

An API secret for OAuth 2.0 authentication. It is recommended that you populate this field using xref:configuration:interpolation.adoc[environment variables].


*Type*: `string`