> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# fetch_twitter_api_io

> Fetch tweets from Twitter/X using TwitterAPI.io advanced search. 

Fetches tweets from Twitter/X using the TwitterAPI.io advanced search API.

Uses Twitter's native advanced search syntax (from:, to:, lang:, since:, until:, OR, etc.).
Returns a dataset with 37 columns: tweet text, author info, engagement metrics,
entities (hashtags, URLs, mentions), media URLs, and quoted/retweeted tweets.

Cost: \~\$0.15 per 1,000 tweets (15 credits per tweet).

## Query Syntax

| Operator           | Example            | Description               |
| ------------------ | ------------------ | ------------------------- |
| `from:`            | `from:NASA`        | Tweets from a user        |
| `to:`              | `to:NASA`          | Tweets replying to a user |
| `lang:`            | `lang:es`          | Filter by language        |
| `since:`           | `since:2026-01-01` | Tweets after date         |
| `until:`           | `until:2026-02-01` | Tweets before date        |
| `OR`               | `cat OR dog`       | Either term               |
| `-`                | `cat -dog`         | Exclude term              |
| `""`               | `"exact phrase"`   | Exact match               |
| `min_faves:`       | `min_faves:100`    | Minimum likes             |
| `filter:media`     | `filter:media`     | Only with media           |
| `-filter:retweets` |                    | Exclude retweets          |

## Error Handling

* **Rate limit (429):** Retries with exponential backoff
* **Credits exhausted (402):** Returns partial data with warning (W41)
* **Timeout:** Returns partial data with warning (W41)

Learn more at [docs.twitterapi.io](https://docs.twitterapi.io).

## Usage

The following example shows how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      Fetch tweets about climate change in English

      ```stan theme={null}
      fetch_twitter_api_io({
          "integration": "MY_TWITTER_API_IO",
          "query": "\"climate change\" lang:en since:2026-01-01",
          "query_type": "Latest",
          "max_items": 5000
      }) -> (ds_out)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      fetch_twitter_api_io(, {
          "param": value,
          ...
      }) -> (ds_out: dataset)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket" />

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="ds_out" type="dataset" required>
    The dataset containing tweets from the search.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="integration" type="string" required>
    TwitterAPI.io Integration.
    ID of your TwitterAPI.io integration containing the API key.
  </ParamField>

  <ParamField path="query" type="string" required>
    Search Query.
    Twitter advanced search query. Supports operators: from:, to:, lang:,
    since:YYYY-MM-DD, until:YYYY-MM-DD, OR, -, "exact phrase",
    min\_replies:, min\_faves:, filter:links, filter:media.
    Reference: [https://github.com/igorbrigadir/twitter-advanced-search](https://github.com/igorbrigadir/twitter-advanced-search).
  </ParamField>

  <ParamField path="query_type" type="string" default="Latest">
    Sort Order.
    Sort order. "Latest" for chronological, "Top" for most relevant.

    Values must be one of the following:

    * `Latest`
    * `Top`
  </ParamField>

  <ParamField path="max_items" type="integer">
    Max Tweets.
    Maximum number of tweets to fetch. Leave empty to fetch all matching tweets.
    Cost: \~15 credits per tweet (\$0.15 per 1,000 tweets).
  </ParamField>

  <ParamField path="timeout" type="integer" default="3600">
    Timeout.
    Maximum seconds to wait for the search to complete.
  </ParamField>
</Accordion>