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

# Developer Guidelines

> A practical guide to what's allowed and what's not when building with the X API.

<Warning>
  **Violations can result in app suspension, API access revocation, or permanent account bans.** Always review the official policies before building.
</Warning>

<CardGroup cols={2}>
  <Card title="Developer Agreement" icon="file-contract" href="https://docs.x.com/developer-terms/agreement">
    Binding legal terms for API access
  </Card>

  <Card title="Developer Policy" icon="shield-check" href="https://docs.x.com/developer-terms/policy">
    Rules for building on X
  </Card>

  <Card title="Automation Rules" icon="robot" href="https://help.x.com/en/rules-and-policies/x-automation">
    Specific rules for bots
  </Card>

  <Card title="Restricted Use Cases" icon="ban" href="https://docs.x.com/developer-terms/restricted-use-cases">
    Prohibited activities
  </Card>
</CardGroup>

***

## Quick check: is my app allowed?

Before building, ask yourself these questions. If you answer **"no"** to any of them, your app likely violates X's policies.

<CardGroup cols={2}>
  <Card title="User Initiated?" icon="hand-pointer">
    For interactions, did the user **explicitly request** it?
  </Card>

  <Card title="Transparent?" icon="tag">
    Is your app's purpose and behavior **clear to users**? (Automated accounts must be labeled.)
  </Card>

  <Card title="Easy Opt-Out?" icon="right-from-bracket">
    Can users **easily opt out** of any ongoing interactions?
  </Card>

  <Card title="Real Value?" icon="gem">
    Does it provide **real value** beyond self-promotion?
  </Card>

  <Card title="Official API Only?" icon="code">
    Are you **only using the official API** (not scraping/browser automation)?
  </Card>

  <Card title="Within Limits?" icon="gauge">
    Are you **within rate limits** and respecting usage policies?
  </Card>
</CardGroup>

<Tip>
  When in doubt, ask: "Would a user be happy with this experience?" If not, reconsider your approach.
</Tip>

***

## Common scenarios: allowed or not?

Real-world examples to help you understand what's permitted. **These rules apply to all apps**—whether you're building a bot, mobile app, web integration, browser extension, analytics dashboard, or any other tool that uses the X API.

<Tabs>
  <Tab title="Content & Posting">
    | Scenario                                                              |                   Allowed?                   | Why                                                |
    | --------------------------------------------------------------------- | :------------------------------------------: | -------------------------------------------------- |
    | Automated account posts scheduled content (news, weather, quotes)     | <Icon icon="circle-check" color="#22c55e" /> | Informational, no unsolicited mentions             |
    | App posts RSS feed updates on behalf of user                          | <Icon icon="circle-check" color="#22c55e" /> | Helpful broadcasting                               |
    | Alert service posts earthquake/disaster notifications                 | <Icon icon="circle-check" color="#22c55e" /> | Public safety value                                |
    | Sports app posts game updates to user's timeline                      | <Icon icon="circle-check" color="#22c55e" /> | Informational                                      |
    | App posts stock/crypto prices on schedule                             | <Icon icon="circle-check" color="#22c55e" /> | Informational, no manipulation                     |
    | App posts identical content across multiple accounts                  | <Icon icon="circle-xmark" color="#ef4444" /> | Spam / platform manipulation                       |
    | App posts to trending topics to gain visibility                       | <Icon icon="circle-xmark" color="#ef4444" /> | Trend manipulation                                 |
    | Multiple city-specific alert accounts (e.g., @WeatherNYC, @WeatherLA) | <Icon icon="circle-check" color="#22c55e" /> | Allowed—non-duplicative, location-specific content |
  </Tab>

  <Tab title="Replies & Mentions">
    | Scenario                                               |                       Allowed?                       | Why                                                                         |
    | ------------------------------------------------------ | :--------------------------------------------------: | --------------------------------------------------------------------------- |
    | App responds to @mentions asking for help              |     <Icon icon="circle-check" color="#22c55e" />     | User-initiated request                                                      |
    | App auto-replies to anyone mentioning a keyword        |     <Icon icon="circle-xmark" color="#ef4444" />     | Unsolicited interaction                                                     |
    | App auto-replies to users who reply to your post       |     <Icon icon="circle-check" color="#22c55e" />     | User engaged first—limit 1 reply. [Conditions apply](#gray-areas-explained) |
    | AI-powered app generates and posts replies             | <Icon icon="triangle-exclamation" color="#f59e0b" /> | Requires **prior approval** from X                                          |
    | App replies with "follow me for more!" to random users |     <Icon icon="circle-xmark" color="#ef4444" />     | Spam, unsolicited                                                           |
    | Utility app that unrolls threads when mentioned        |     <Icon icon="circle-check" color="#22c55e" />     | User-initiated utility                                                      |
  </Tab>

  <Tab title="Direct Messages">
    | Scenario                                                  |                   Allowed?                   | Why                                                                     |
    | --------------------------------------------------------- | :------------------------------------------: | ----------------------------------------------------------------------- |
    | App responds to DMs with helpful info                     | <Icon icon="circle-check" color="#22c55e" /> | User-initiated                                                          |
    | App sends affiliate links when user DMs first             | <Icon icon="circle-check" color="#22c55e" /> | User-initiated—must disclose. [Conditions apply](#gray-areas-explained) |
    | App auto-DMs new followers with welcome message           | <Icon icon="circle-xmark" color="#ef4444" /> | Unsolicited, even to followers                                          |
    | App bulk-DMs users about a product launch                 | <Icon icon="circle-xmark" color="#ef4444" /> | Spam                                                                    |
    | Support integration asks "How can I help?" after user DMs | <Icon icon="circle-check" color="#22c55e" /> | User-initiated conversation                                             |
  </Tab>

  <Tab title="Engagement">
    | Scenario                                              |                   Allowed?                   | Why                                                                                    |
    | ----------------------------------------------------- | :------------------------------------------: | -------------------------------------------------------------------------------------- |
    | Third-party app lets user tap a like button on a post | <Icon icon="circle-check" color="#22c55e" /> | User-initiated through the app                                                         |
    | App auto-likes posts containing a hashtag             | <Icon icon="circle-xmark" color="#ef4444" /> | Automated, not user-initiated                                                          |
    | Mobile app has "auto-like" feature for selected users | <Icon icon="circle-xmark" color="#ef4444" /> | Automated, not user-initiated                                                          |
    | Service sells likes or offers "bulk like" packages    | <Icon icon="circle-xmark" color="#ef4444" /> | Selling engagement is prohibited                                                       |
    | App reposts content from a curated list               | <Icon icon="circle-check" color="#22c55e" /> | OK for informational purposes, no bulk spam. [Conditions apply](#gray-areas-explained) |
    | Growth tool bulk-follows accounts to grow audience    | <Icon icon="circle-xmark" color="#ef4444" /> | Manipulation                                                                           |
    | App follows back anyone who follows it                | <Icon icon="circle-xmark" color="#ef4444" /> | Bulk/aggressive following                                                              |
    | App adds users to lists in bulk                       | <Icon icon="circle-xmark" color="#ef4444" /> | Indiscriminate list manipulation                                                       |

    <Warning>**Likes must be directly initiated by the authenticated user.** Automated, bulk, or indiscriminate liking — including auto-liking by keyword, hashtag, user, or schedule — is prohibited. Apps may not offer "auto-like" features or sell likes as a service. This applies to all apps—bots, mobile apps, browser extensions, or any integration.</Warning>
  </Tab>

  <Tab title="Promotions & Commerce">
    | Scenario                                             |                       Allowed?                       | Why                                                                                         |
    | ---------------------------------------------------- | :--------------------------------------------------: | ------------------------------------------------------------------------------------------- |
    | App sends product recommendations when asked         |     <Icon icon="circle-check" color="#22c55e" />     | User-initiated                                                                              |
    | App replies to random posts with affiliate links     |     <Icon icon="circle-xmark" color="#ef4444" />     | Unsolicited spam                                                                            |
    | Giveaway app that requires follows/retweets to enter | <Icon icon="triangle-exclamation" color="#f59e0b" /> | Risky—can be seen as engagement manipulation                                                |
    | Service selling likes/follows/retweets               |     <Icon icon="circle-xmark" color="#ef4444" />     | Strictly prohibited                                                                         |
    | Tip service that sends crypto when user requests     |     <Icon icon="circle-check" color="#22c55e" />     | User-initiated—comply with financial regulations. [Conditions apply](#gray-areas-explained) |
  </Tab>

  <Tab title="Data & Research">
    | Scenario                                          |                   Allowed?                   | Why                               |
    | ------------------------------------------------- | :------------------------------------------: | --------------------------------- |
    | App tracks brand mentions for analytics dashboard | <Icon icon="circle-check" color="#22c55e" /> | Valid use case                    |
    | App scrapes X via browser automation (not API)    | <Icon icon="circle-xmark" color="#ef4444" /> | **Permanent suspension**—API only |
    | App stores X data to train AI/ML models           | <Icon icon="circle-xmark" color="#ef4444" /> | Prohibited (except Grok)          |
    | App redistributes >1.5M posts in 30 days          | <Icon icon="circle-xmark" color="#ef4444" /> | Exceeds redistribution limits     |
    | App benchmarks X performance vs competitors       | <Icon icon="circle-xmark" color="#ef4444" /> | Prohibited competitive analysis   |
    | Academic research on public conversation trends   | <Icon icon="circle-check" color="#22c55e" /> | Valid with proper data handling   |

    <Danger>
      **Non-API automation (scraping, browser automation) results in permanent suspension.** Always use the official X API.
    </Danger>
  </Tab>
</Tabs>

***

## Prohibited activities

<Warning>
  These activities will get your app suspended or permanently banned. There are no exceptions.
</Warning>

| Category                      | Examples                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| **Spam & Manipulation**       | Identical content across accounts, fake engagement, trend manipulation, bulk posting |
| **Unsolicited Outreach**      | Auto-replies to random users, bulk DMs, uninvited @mentions                          |
| **Deceptive Bots**            | Impersonating humans, hiding bot identity, misleading links/redirects                |
| **Engagement Selling**        | Apps that sell likes, follows, retweets, or views                                    |
| **Rate Limit Abuse**          | Exceeding limits, designing apps that encourage overuse                              |
| **Non-API Automation**        | Browser scripting, scraping, any automation outside official API                     |
| **Account Farms**             | Multiple accounts for same duplicative purpose                                       |
| **Surveillance**              | Profiling, tracking, or monitoring users without consent                             |
| **Unauthorized AI Training**  | Using X data to train ML models (Grok excepted)                                      |
| **Sensitive Data Derivation** | Inferring health, political, religious, or other sensitive attributes                |
| **Excessive Redistribution**  | Sharing >1.5M Post IDs per 30-day period                                             |

***

## Automation rules

<Note>
  This section applies specifically to **automated accounts** (bots) that post, reply, or interact on behalf of users. If you're building an analytics dashboard, research tool, or other non-automated app, these labeling requirements don't apply to you—but the technical restrictions still do.
</Note>

### Requirements for automated accounts

All automated accounts using the X API must meet these requirements:

<Steps>
  <Step title="Enable the 'Automated' profile label">
    This label appears under your bot's name/handle on its profile. Enable it in your app settings to ensure transparency.
  </Step>

  <Step title="Disclose in bio">
    State clearly that it's a bot and who operates it. Example: *"Bot by @yourcompany"* or *"Automated account managed by Example Inc."*
  </Step>

  <Step title="Link to a human-managed account">
    For accountability and contact purposes, your bot must be associated with a human-managed account.
  </Step>

  <Step title="Honor opt-out requests immediately">
    If a user says "stop," stop. Implement keyword detection for common opt-out phrases.
  </Step>

  <Step title="Use only the official X API">
    No scraping, browser automation, or unofficial methods. Violations result in permanent suspension.
  </Step>

  <Step title="Stay within rate limits">
    Don't try to circumvent or abuse rate limits. Design your app to handle limits gracefully.
  </Step>
</Steps>

### Automated actions: what's allowed?

| Action              |                       Allowed?                       | Rules                                                                                        |
| ------------------- | :--------------------------------------------------: | -------------------------------------------------------------------------------------------- |
| **Post tweets**     |     <Icon icon="circle-check" color="#22c55e" />     | No unsolicited @mentions. No identical cross-posting.                                        |
| **Reply to users**  | <Icon icon="triangle-exclamation" color="#f59e0b" /> | Only if user engaged first. Max **1 reply per interaction**.                                 |
| **Send DMs**        | <Icon icon="triangle-exclamation" color="#f59e0b" /> | Only after user DMs you first. Easy opt-out required.                                        |
| **Like posts**      | <Icon icon="triangle-exclamation" color="#f59e0b" /> | Must be directly user-initiated. Auto-liking, bulk liking, and selling likes are prohibited. |
| **Repost**          | <Icon icon="triangle-exclamation" color="#f59e0b" /> | OK for informational/entertainment. No bulk spam.                                            |
| **Quote tweet**     | <Icon icon="triangle-exclamation" color="#f59e0b" /> | Same rules as repost—no spam or manipulation.                                                |
| **Follow/Unfollow** |     <Icon icon="circle-xmark" color="#ef4444" />     | No bulk, aggressive, or automated following.                                                 |
| **Add to Lists**    | <Icon icon="triangle-exclamation" color="#f59e0b" /> | No bulk or indiscriminate additions.                                                         |
| **Bookmark**        |     <Icon icon="circle-check" color="#22c55e" />     | Fine for personal/automated use.                                                             |
| **Search/Read**     |     <Icon icon="circle-check" color="#22c55e" />     | Standard use within rate limits.                                                             |

***

## Gray areas explained

Many developers have questions about edge cases. Here's guidance on common gray areas.

<AccordionGroup>
  <Accordion title="Affiliate Links & Promotions" icon="link">
    <Check>
      **Allowed if:**

      * User explicitly requests it (e.g., DMs asking for a recommendation)
      * You clearly disclose the affiliate/sponsored relationship
      * Links are not misleading (no deceptive redirects)
    </Check>

    <Warning>
      **Not allowed if:**

      * You auto-reply to random posts with affiliate links
      * You DM users who didn't ask
      * You hide the commercial relationship
    </Warning>
  </Accordion>

  <Accordion title="AI-Generated Content & Replies" icon="microchip-ai">
    * **Requires prior approval from X** before deployment
    * Must still follow all rules (no unsolicited mentions, properly labeled)
    * Contact X via the [Policy Support form](https://help.x.com/forms/platform) before launching
    * Even with approval, cannot impersonate humans

    <Warning>Deploying AI-generated replies without approval is a violation, even if the content itself is helpful.</Warning>
  </Accordion>

  <Accordion title="Welcome Messages to New Followers" icon="envelope">
    **Not allowed** as automated DMs—this counts as unsolicited contact, even though they followed you.

    **Alternatives:**

    * Pinned tweet welcoming new followers
    * Bio with intro info and links
    * Auto-reply only if they DM you first
  </Accordion>

  <Accordion title="Multiple Accounts / Regional Bots" icon="globe">
    <Check>
      **Allowed if:**

      * Each account serves **non-duplicative** purposes (e.g., @EarthquakeJP, @EarthquakeCA)
      * Content is meaningfully different (location-specific, language-specific)
      * Not used to bypass limits or amplify the same message
    </Check>

    <Warning>
      **Not allowed if:**

      * Posting identical/similar content across accounts
      * Created to evade suspensions or rate limits
    </Warning>
  </Accordion>

  <Accordion title="Customer Support Automation" icon="headset">
    <Check>
      **Allowed if:**

      * User initiates (mentions you, DMs you, or explicitly opts in)
      * Clear opt-out mechanism exists
      * Responses are helpful, not promotional
      * Includes privacy policy link in DMs
    </Check>

    <Warning>
      **Not allowed if:**

      * You reach out to users who complained publicly (unsolicited)
      * Responses are primarily promotional
    </Warning>
  </Accordion>

  <Accordion title="Giveaways & Contests" icon="gift">
    **Proceed with caution:**

    * Requiring follows/retweets as entry can be seen as engagement manipulation
    * Must comply with [X's contest guidelines](https://help.x.com/en/rules-and-policies/x-contest-rules)
    * Don't use multiple accounts to amplify
    * Ensure prizes are real and delivered

    <Tip>Consider entry methods that don't require engagement actions, like replying with a specific phrase.</Tip>
  </Accordion>
</AccordionGroup>

***

## Data handling and display requirements

<Warning>
  These requirements are legally binding under the Developer Agreement. Non-compliance can result in termination and legal action.
</Warning>

### Content deletion

You must delete X Content from your systems when requested:

| Trigger                           | Deadline                                      |
| --------------------------------- | --------------------------------------------- |
| X requests deletion               | **24 hours**                                  |
| User requests deletion            | **24 hours**                                  |
| Content is suspended/removed on X | **24 hours**                                  |
| Your API access is terminated     | **10 business days** (must delete all X data) |

<Tip>
  Use [Compliance Firehose](https://docs.x.com/x-api/compliance/streams) to receive real-time deletion events and stay compliant automatically.
</Tip>

### Off-X matching

**Off-X matching** means associating X data (username, user ID, posts) with off-platform identifiers (your customer database, email lists, device IDs, etc.).

<Check>
  **Allowed with express opt-in consent:**

  * User explicitly agrees to link their X account with your service
  * Clear disclosure of what data will be matched and why
</Check>

<Warning>
  **Without consent, you may only match:**

  * Information the user directly provided to you
  * Publicly available X data (posts, bio, display name, username)
  * Public resources like professional directories

  **Never match if it would surprise the user.**
</Warning>

### Sensitive data

<Danger>
  You **cannot** derive, infer, or store information about X users in these categories:
</Danger>

| Category                        | Examples                                     |
| ------------------------------- | -------------------------------------------- |
| **Health**                      | Medical conditions, pregnancy, disabilities  |
| **Financial status**            | Negative financial condition, credit issues  |
| **Political**                   | Party affiliation, political beliefs, voting |
| **Racial/Ethnic**               | Origin, ethnicity                            |
| **Religious/Philosophical**     | Beliefs, affiliations                        |
| **Sex life/Sexual orientation** | Any inference about sexuality                |
| **Trade union**                 | Membership or affiliation                    |
| **Criminal**                    | Alleged or actual criminal activity          |

<Note>
  **Exception:** Aggregate analysis without storing personal identifiers (no user IDs, usernames, or linkable data) may be allowed for research purposes, subject to applicable laws.
</Note>

### Displaying X content

| Requirement          | Details                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| **Attribution**      | Use proper X branding. Follow [Brand Guidelines](https://about.x.com/en/who-we-are/brand-toolkit).       |
| **No alterations**   | Only modify for display formatting (resizing). Don't edit content, remove timestamps, or strip metadata. |
| **No iframes**       | Don't display X Content in iframes. Use official embeds or render directly.                              |
| **Respect removals** | Remove content within 24 hours if deleted on X.                                                          |

***

## Technical restrictions

<Note>
  These limits apply to all developers. Exceeding them can result in rate limiting or suspension.
</Note>

| Restriction                         | Limit                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------- |
| **Post ID redistribution**          | Max 1.5M Post IDs per 30-day period to any single entity                  |
| **Hydrated content redistribution** | Max 50,000 hydrated Posts or Users per recipient per day                  |
| **Rate limits**                     | Vary by endpoint and tier—[see API docs](/x-api/fundamentals/rate-limits) |
| **AI/ML training**                  | Prohibited (except for Grok)                                              |
| **Non-API access**                  | Prohibited—scraping and browser automation = permanent ban                |
| **Competitive benchmarking**        | Prohibited—can't measure X performance vs. competitors                    |
| **Multiple apps for same use case** | Prohibited—don't create duplicate apps to bypass limits                   |

### Special use cases

| Use Case                             | Requirement                                                      |
| ------------------------------------ | ---------------------------------------------------------------- |
| **Government use**                   | Requires Enterprise tier                                         |
| **Commercial use**                   | Requires appropriate paid tier; free tier is non-commercial only |
| **Academic research**                | May have different redistribution limits; contact X for details  |
| **EU Digital Services Act research** | Specific non-commercial research provisions available            |

***

## Security and compliance

Your obligations as a developer:

<AccordionGroup>
  <Accordion title="Security Requirements" icon="shield">
    * Use **industry-standard security** practices to protect X data
    * Never share your API credentials or tokens
    * Store credentials securely (environment variables, secret managers—not in code)
    * Implement proper authentication in your apps
  </Accordion>

  <Accordion title="Breach Notification" icon="bell">
    If you experience a security breach involving X data:

    * **Notify X immediately**
    * Take steps to mitigate the breach
    * Cooperate with X's investigation
  </Accordion>

  <Accordion title="Confidentiality" icon="lock">
    * Treat any non-public information from X as confidential
    * Don't disclose API rate limits, internal X data, or non-public features
    * Don't use confidential info for competitive purposes
  </Accordion>

  <Accordion title="Audit Rights" icon="magnifying-glass">
    * X may audit your compliance **up to once per year**
    * You must provide reasonable access and documentation
    * Keep records of how you use X data
  </Accordion>
</AccordionGroup>

***

## Summary: do's and don'ts

<Tabs>
  <Tab title="Do" icon="circle-check" iconColor="#22c55e">
    **For Automated Accounts:**

    * Enable "Automated" profile label
    * Disclose operator in bio
    * Wait for users to initiate interaction
    * Provide easy opt-out
    * Get approval for AI-generated replies

    **For All Apps:**

    * Use only the official X API
    * Respect rate limits and redistribution limits
    * Delete content within 24 hours when requested
    * Get opt-in consent for off-X matching
    * Use proper attribution when displaying X Content
    * Secure your credentials and notify X of breaches
    * Keep records of your X data usage
  </Tab>

  <Tab title="Don't" icon="circle-xmark" iconColor="#ef4444">
    **For Automated Accounts:**

    * Hide automated nature
    * Send unsolicited DMs, replies, or @mentions
    * Ignore "stop" requests
    * Post identical content across accounts
    * Auto-like, bulk-like, or sell likes (likes must be user-initiated)

    **For All Apps:**

    * Scrape or use browser automation
    * Train AI/ML models on X data (except Grok)
    * Derive sensitive user data (health, politics, religion, etc.)
    * Match X data to off-platform IDs without consent
    * Display X Content in iframes
    * Redistribute more than limits allow
    * Create multiple apps for the same use case
    * Use X data for surveillance or user tracking
  </Tab>
</Tabs>