> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/social-media/x-twitter-public-data.md).

# X (Twitter) Public Data

Export public X (Twitter) posts and author profiles that match a search query to Google Sheets, BigQuery, AI tools, and more with Coupler.io.

X (Twitter) Public Data exports public posts that match a search query you write, along with the profiles of the accounts that posted them. Use it to track mentions of your brand, a hashtag, a competitor, or a topic, and send the results to a spreadsheet, warehouse, BI tool, or AI tool on a schedule.

Coupler.io uses your own X API Bearer Token and X's recent search, so it returns posts from the last 7 days. Scheduled runs fetch incrementally, so your history keeps growing in Coupler.io beyond that window.

**Why connect X (Twitter) Public Data to Coupler.io?**

* Monitor brand mentions, hashtags, and competitor accounts without searching X by hand
* Keep posts older than X's 7-day search window by refreshing on a schedule
* See who is talking about a topic, with follower counts and verification status for each author
* Combine X mentions with ads, web analytics, or CRM data in the Data sets step
* Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, or other supported destinations

## Prerequisites

* An X developer account with a Project and an App in the [X Developer Portal](https://developer.x.com/en/portal/dashboard)
* An X API plan that includes recent search (`GET /2/tweets/search/recent`). Every post Coupler.io fetches counts toward your plan's read usage
* The App-only **Bearer Token** of that App, from **Keys and tokens** in the Developer Portal\
  ![](https://1055512216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFxU2LUkJMCfvbE2re5C%2Fuploads%2FATyE7DChvnS2m5fPKhFr%2Fimage.png?alt=media\&token=cdc9aa21-c2fd-48d2-b155-672e324bdb43)

{% hint style="info" %}
The connection is read-only. Coupler.io doesn't post, like, follow, or change anything on X.
{% endhint %}

## Quick start

{% hint style="success" %}
Start with the **Tweets** entity, a narrow query such as `"your brand" -is:retweet lang:en`, and **Limit results to 100** turned on. Check the rows in the preview, then widen the query or turn the limit off once you know how many posts it matches.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** Select **X (Twitter) Public data** as your source and click **Connect**.\
Paste your App-only Bearer Token from the X Developer Portal and save the connection.
{% endstep %}

{% step %}
**Choose a data entity.** In **Data entity**, select **Tweets** for the posts or **Authors** for the profiles of the accounts that posted them.
{% endstep %}

{% step %}
**Enter a search query.** In **Search query**, enter a query in X search syntax, for example `#coupler OR @coupler_io -is:retweet`. See [Search query](#search-query) for the operators you can use.
{% endstep %}

{% step %}
**Set advanced settings.** Optionally pick a **Start date** and **End date** with the date picker, and turn on **Limit results to 100** to cap X API usage. Leave the dates empty to fetch the last 7 days.
{% endstep %}

{% step %}
**Choose a destination.** Select where the data should land, such as Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** for the first sync, then set a schedule so new posts keep arriving.
{% endstep %}
{% endstepper %}

## X (Twitter) Public Data data overview

X (Twitter) Public Data has two data entities. Both come from the same search: you write one query, and Coupler.io returns either the matching posts or the accounts that wrote them. Each source returns one entity, so to get both, add the source twice in the same data flow with the same query.

## Data entities

| Data entity | One row per                         | Best for                                                           |
| ----------- | ----------------------------------- | ------------------------------------------------------------------ |
| Tweets      | Post that matches the search query  | Mention tracking, hashtag monitoring, content and topic analysis   |
| Authors     | Account that posted a matching post | Finding who drives a conversation, influencer lists, audience size |

## Configuration options

### Search query

**Search query** is required. It uses X's search operators. On self-serve X API plans, a query can be up to 512 characters (Enterprise allows more). Common operators:

| Operator          | Example                             | Matches                                     |
| ----------------- | ----------------------------------- | ------------------------------------------- |
| Keyword or phrase | `coupler`, `"data integration"`     | Posts that contain the word or exact phrase |
| Hashtag           | `#nocode`                           | Posts with the hashtag                      |
| Mention           | `@coupler_io`                       | Posts that mention the account              |
| From an account   | `from:coupler_io`                   | Posts written by the account                |
| `OR` and grouping | `(coupler OR "coupler.io") lang:en` | Either term, in English                     |
| Exclude           | `-is:retweet`, `-is:reply`          | Removes reposts or replies                  |
| Language          | `lang:de`                           | Posts X detected as German                  |
| Has               | `has:links`, `has:media`            | Posts with links or media                   |

Terms separated by a space are combined with AND. Some operators are limited to certain X API access levels. See X's [build a query guide](https://docs.x.com/x-api/posts/search/integrate/build-a-query) for the full list.

### Start date and End date

X recent search only covers the last 7 days, so:

* **Start date** can't be more than 7 days in the past. Leave it empty to start 7 days ago.
* **End date** must be at least 10 seconds before the run. Leave it empty to fetch up to the moment the data flow runs.

Set dates with the date picker. For a rolling window, you can use date macros instead. See [Macros in data flows](https://docs.coupler.io/functionality/macros-in-data-flows).

### Limit results to 100

When on, each run fetches only the first page of results (up to 100 posts or authors), which keeps X API usage low. When off, Coupler.io pages through every match in the date range. The switch is off by default.

## Sync behavior

Both entities sync incrementally, and new rows are added to the data already kept in [Coupler.io Storage](https://docs.coupler.io/functionality/coupler.io-storage).

* **Tweets**: the first run fetches the date range you set. Each later run continues from the newest post already fetched.
* **Authors**: each run searches the full date range again, because an author's `created_at` is the account creation date, not a post date.

This lets you build a history of mentions longer than X's 7-day search window, as long as the data flow runs at least once every 7 days.

## Data schema

### Tweets

| Field                                     | Description                                                      |
| ----------------------------------------- | ---------------------------------------------------------------- |
| `id`                                      | Post ID. Open a post at `https://x.com/i/status/<id>`            |
| `text`                                    | Post text                                                        |
| `created_at`                              | When the post was published, in UTC                              |
| `author_id`                               | ID of the posting account. Matches `id` in **Authors**           |
| `conversation_id`                         | ID of the original post in the thread                            |
| `in_reply_to_user_id`                     | Account the post replies to, if it's a reply                     |
| `referenced_tweets`                       | Posts this one quotes, replies to, or reposts, with their `type` |
| `lang`                                    | Language X detected for the post                                 |
| `entities`                                | Hashtags, mentions, cashtags, and URLs found in the text         |
| `context_annotations`                     | Topics and named entities X detected, such as brands or people   |
| `attachments`                             | Media keys and poll IDs                                          |
| `geo`                                     | Place ID, if the author tagged a location                        |
| `possibly_sensitive`                      | Whether the post may contain sensitive content                   |
| `reply_settings`                          | Who can reply to the post                                        |
| `edit_controls`, `edit_history_tweet_ids` | Edit status and the IDs of earlier versions                      |

{% hint style="info" %}
The **Tweets** entity doesn't include engagement counts such as likes, reposts, replies, or views.
{% endhint %}

### Authors

| Field                       | Description                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id`                        | Account ID                                                                                                              |
| `username`                  | Handle without `@`                                                                                                      |
| `name`                      | Display name                                                                                                            |
| `description`               | Profile bio                                                                                                             |
| `location`                  | Location the user entered on the profile                                                                                |
| `url`                       | Website link from the profile                                                                                           |
| `profile_image_url`         | Profile picture URL                                                                                                     |
| `created_at`                | When the account was created, not when it posted                                                                        |
| `verified`, `verified_type` | Verification status and type, such as `blue`, `business`, or `government`                                               |
| `protected`                 | Whether the account's posts are protected                                                                               |
| `pinned_tweet_id`           | ID of the pinned post                                                                                                   |
| `public_metrics`            | `followers_count`, `following_count`, `tweet_count`, `listed_count`, `like_count`, `media_count` at the time of the run |
| `entities`                  | Hashtags, mentions, and URLs in the bio and profile link                                                                |

Each row in **Authors** is the account as it was when the data flow ran. An account that posted several matching posts can appear more than once.

## Common field combinations

| Goal                           | Data entity      | Fields to use                            |
| ------------------------------ | ---------------- | ---------------------------------------- |
| Mentions per day               | Tweets           | `created_at`, `id`                       |
| Top hashtags in a conversation | Tweets           | `entities` (hashtags)                    |
| Mentions by language           | Tweets           | `lang`, `id`                             |
| Who has the largest reach      | Authors          | `username`, `public_metrics` (followers) |
| Mentions with author details   | Tweets + Authors | Join `author_id` to `id`                 |

## Use cases by role

{% tabs %}
{% tab title="Social media managers" %}

* Track mentions of your brand and handle every day, and build a mention history past X's 7-day window
* Spot replies and questions that need an answer by filtering on `in_reply_to_user_id` and `conversation_id`
* Watch campaign hashtags and see how volume changes after each launch
  {% endtab %}

{% tab title="Marketing and PR teams" %}

* Compare share of voice by running the same query for your brand and competitors as separate sources in one data flow
* Find accounts with the most followers talking about your topic, for outreach and influencer lists
* Send mentions to Claude or ChatGPT to summarize themes and sentiment
  {% endtab %}

{% tab title="Analysts" %}

* Load posts into BigQuery and analyze trends by day, language, or topic from `context_annotations`
* Join Tweets to Authors on `author_id` to segment mentions by verified status or audience size
* Combine mention volume with web traffic or ad spend by date in the Data sets step
  {% endtab %}
  {% endtabs %}

## X (Twitter) Public Data common issues

### Connection issues

<details>

<summary>"Unauthorized" (401) error when connecting or running the data flow</summary>

X didn't accept the Bearer Token. This happens when the token was copied incompletely, or it was regenerated or revoked in the Developer Portal. Copy the current App-only Bearer Token from **Keys and tokens**, update the connection in Coupler.io, and run the data flow again.

</details>

<details>

<summary>"Forbidden" (403) error or "client-not-enrolled"</summary>

Your App can't call recent search. Check that the App belongs to a Project in the Developer Portal and that your X API plan includes recent search. Then generate the Bearer Token for that App and reconnect.

</details>

### Query and date errors

<details>

<summary>Error about an invalid query</summary>

X rejects queries with syntax errors, unsupported operators, or more characters than your plan allows (512 on self-serve plans). Check quotes and parentheses, remove operators that your X API access level doesn't support, and shorten long `OR` lists.

</details>

<details>

<summary>Error that the start time or end time is invalid</summary>

**Start date** must be within the last 7 days, and **End date** must be at least 10 seconds before the run. A fixed start date stops working once it's more than 7 days old. Leave **Start date** empty, or use a rolling date macro, so every run stays inside X's window.

</details>

### Missing data

<details>

<summary>The data flow runs but returns no rows</summary>

* The query matched no posts in the last 7 days. Test the same query in X search to confirm.
* The date range is too narrow. Leave **Start date** and **End date** empty to search the full 7 days.
* Posts from protected accounts are never returned.

</details>

<details>

<summary>Fewer posts than expected</summary>

Check whether **Limit results to 100** is on. It stops each run after the first 100 results. Turn it off to fetch every match, if your X API plan allows the extra reads.

</details>

<details>

<summary>Posts older than 7 days are missing</summary>

X recent search can't return them. Coupler.io keeps posts only from runs that already happened, so a gap appears if the data flow didn't run for more than 7 days. Schedule the data flow at least daily to avoid gaps.

</details>

### Rate limits and usage

<details>

<summary>"Too Many Requests" (429) error or usage cap reached</summary>

X limits how often an App can call recent search and how many posts it can read per month, depending on your plan. Coupler.io retries briefly when X returns 429, then fails the run if the limit persists. Turn on **Limit results to 100**, narrow the query, run less often, or upgrade your X API plan. Check usage in the X Developer Portal.

</details>

## X (Twitter) Public Data FAQ

<details>

<summary>How far back can X (Twitter) Public Data fetch posts?</summary>

7 days. Coupler.io uses X recent search, which only covers the last 7 days. Run the data flow on a schedule, and Coupler.io keeps adding new posts to what it already fetched, so your history grows past 7 days.

</details>

<details>

<summary>Where do I find the Bearer Token for X (Twitter) Public Data?</summary>

In the [X Developer Portal](https://developer.x.com/en/portal/dashboard), open your Project, select your App, and go to **Keys and tokens**. Generate or copy the **Bearer Token** under **Authentication Tokens**. Coupler.io uses this App-only token. You don't need the API key and secret or user access tokens.

</details>

<details>

<summary>Does X (Twitter) Public Data include likes, reposts, or views for each post?</summary>

No. The **Tweets** entity returns post content and metadata but no engagement counts. The **Authors** entity includes account-level numbers such as `followers_count` and `tweet_count`. For metrics on your own paid campaigns, use the X (Twitter) Ads source.

</details>

<details>

<summary>Can I get posts and authors in one X (Twitter) Public Data table?</summary>

Add X (Twitter) Public Data twice in the same data flow with the same query, one with **Tweets** and one with **Authors**. Then join them in the Data sets step on `author_id` (Tweets) and `id` (Authors).

</details>

<details>

<summary>Can I track several keywords or hashtags with X (Twitter) Public Data?</summary>

Yes. Combine them in one query with `OR`, such as `#brand OR @brand OR "brand name"`. To keep them in separate tables, add the source several times in the same data flow, one query each, and append them in the Data sets step if needed.

</details>

<details>

<summary>Does X (Twitter) Public Data cost anything on the X side?</summary>

X charges for API access by plan, and every post Coupler.io fetches counts toward your plan's read usage. Turn on **Limit results to 100** and use specific queries to keep usage low. Check current pricing in the [X Developer Portal](https://developer.x.com/en/portal/products).

</details>

<details>

<summary>Can I send X (Twitter) Public Data to Claude, ChatGPT, or other AI tools?</summary>

Yes. Coupler.io supports AI destinations such as Claude, ChatGPT, Gemini, Cursor, Perplexity, and OpenClaw. Send mentions to one of them to summarize topics, sentiment, or recurring questions.

</details>

{% hint style="info" %}
For setup tips, see [X (Twitter) Public Data Best Practices](https://docs.coupler.io/sources/category/social-media/x-twitter-public-data/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/social-media/x-twitter-public-data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
