Skip to content
Nappai Documentation

X Reader

Interact with the X API to retrieve tweets information

How it Works

The X Reader component talks to the X (formerly Twitter) API to fetch tweet data. When you choose an operation, the component sends a request to the X API using the credentials you set up in Nappai. The API returns the requested data, which the component then passes on as a Data output that can be used by other components or as a Tool output for the AI agent.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

  • Get Tweet: Retrieve a single tweet by its ID.
  • Get Recent Tweets: Search for recent tweets that match a query.
  • Get User Timeline: Get the most recent tweets from a specific user’s timeline.
  • Get Tweets By User: Retrieve tweets posted by a specific user.
  • Get Liking Users: Get the list of users who liked a particular tweet.
  • Get users who retweet: Get the list of users who retweeted a particular tweet.
  • Get Quote Tweets: Get the list of tweets that quote a particular tweet.

To use the component, first select the operation you need in the “Operation” field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Operation: Choose the action you want the component to perform.

    • Visible in: Get Tweet, Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Mapping Mode: Enable mapping mode to process multiple data records in batch.

    • Visible in: Get Tweet, Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Max Results: Maximum number of results to return.

    • Visible in: Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Mode: Choose between a simplified setup with default options or full control with advanced settings.

    • Visible in: Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Query: Search term or filter to match recent Tweets.

    • Visible in: Get Recent Tweets

  • Tweet ID: The unique ID of the Tweet to retrieve.

    • Visible in: Get Tweet, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Username: The username of the account whose Tweets or timeline will be retrieved.

    • Visible in: Get User Timeline, Get Tweets By User

  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.

    • Visible in: Get Tweet, Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.

    • Visible in: Get Tweet, Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

  • Tools arguments metadata: Defines the arguments metadata for the tools.

    • Visible in: Get Tweet, Get Recent Tweets, Get User Timeline, Get Tweets By User, Get Liking Users, Get users who retweet, Get Quote Tweets

Credential: This component requires an X API credential.

  1. Configure an X API credential in Nappai’s credentials section.
  2. Select that credential in the Credential field of this component.

Outputs

  • Data: The raw tweet data returned from the X API.
  • Tool: A tool representation that can be used by the AI agent.

Usage Example

Scenario: You want to fetch the 5 most recent tweets that mention “AI” and then let an AI agent decide what to do with them.

  1. Drag the X Reader component onto the canvas.
  2. In the Operation field, select Get Recent Tweets.
  3. Set Query to AI.
  4. Set Max Results to 5.
  5. Choose Mode as Simplified (or Advanced if you need more control).
  6. In the Credential field, pick the X API credential you created earlier.
  7. Connect the Data output to the next component that will process the tweets, or connect the Tool output to the agent’s toolkit.

The component will call the X API, retrieve the tweets, and pass them forward for further processing.

  • X Writer – Write data back to X (e.g., post a tweet).
  • X Base Reader – Base class that provides common functionality for X components.

Tips and Best Practices

  • Use Mapping Mode when you need to process a list of tweet IDs or usernames in bulk.
  • Keep Max Results within the limits of the X API (usually 100 per request).
  • Set a descriptive Tool Name and Tool Description so the AI agent can choose the right tool.
  • If you only need a single tweet, use Get Tweet to avoid unnecessary API calls.
  • Test your queries in the X API Explorer first to ensure they return the expected results.

Security Considerations

  • Store your X API credentials securely in Nappai’s credential store; never expose them in the workflow.
  • Use the Credential field to reference the stored credential instead of entering keys directly.
  • Review the X API rate limits and handle errors gracefully to avoid hitting limits.