URL: /code/integrations/x · Id: `page:/code/integrations/x`

# X

> Your agents post and reply as you, answer direct messages, and hear every mention as it lands; you see what X bills before each post.

Your agents post and reply as you, answer direct messages, and hear every mention as it lands; you see what X bills before each post.

```text title="Run it · Ask"
Find this week’s posts on X from property managers chasing late rent, spend up to 10¢.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Keyword.search({ keyword: 'late rent', venue: 'x', within: '7d', maxCost: 0.1 })
```

```json title="Run it · Response"
{
  "$type": "Keyword",
  "mode": "try",
  "stored": false,
  "keyword": "late rent",
  "venue": "x",
  "results": [
    {
      "position": 1,
      "kind": "post",
      "author": {
        "handle": "@pm_in_tacoma"
      },
      "title": "Third month in a row chasing the same four tenants. There has to be a better way than texting each one.",
      "publishedAt": "2026-10-25T14:02:11Z",
      "engagement": {
        "replies": 14,
        "reposts": 3
      }
    },
    {
      "position": 2,
      "kind": "post",
      "author": {
        "handle": "@duplexdiaries"
      },
      "title": "What do you use to track rent for 40 units? My spreadsheet broke again.",
      "publishedAt": "2026-10-24T22:41:09Z",
      "engagement": {
        "replies": 9,
        "reposts": 1
      }
    }
  ],
  "cost": {
    "usd": 0.0008,
    "maxUsd": 0.1
  }
}
```

- **Connect:** Sign in once, 4 grants
- **Runs through:** [Your account](/code/integrations#three-ways)
- **First run:** Find this week’s posts on your problem, about 0.03¢
- **Sites:** [X](/venues#x)

## Connect once
1. Call `Integration.connect` with `system: 'social'` and `venue: 'x'`, then open the `connectUrl` it returns and sign in as the X account you post from.
2. Approve the grants X lists; leave out direct messages if your agents should only post and reply.
3. Call `Handle.connect` to bind the account as your account, then set a monthly X spend on its standing approval.

| Grant | What it unlocks | Scope |
| --- | --- | --- |
| Post and reply | Posts, threads and replies as you, and deleting your own | `tweet.read tweet.write users.read` |
| Direct messages | Read and answer the direct messages people send you | `dm.read dm.write` |
| Likes and follows | Like a reply, follow back the people who engage | `like.write follows.write` |
| Stay connected | A refresh token, so your agents keep working past X’s two-hour access token | `offline.access` |

| To | Do this |
| --- | --- |
| Pause | `Integration.pause` stops every call through X at once and keeps the token; `Integration.resume` picks up from the same cursor. |
| Reconnect | `Integration.reconnect` returns a fresh `connectUrl` that lasts one hour, and keeps the Integration's id and cursor, so nothing imports twice. |
| Disconnect | `Integration.revoke` revokes the token with X; every record it brought in stays in your records. |

## What your agents do
| Ask | Verb | Runs through | Price |
| --- | --- | --- | --- |
| Post this as me, with the two screenshots. | [`Post.publish`](/code/apps/social/publish) | Your account | About 1.5¢ a post |
| Reply to the best of those posts with the three-step fix. | [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | Your account | About 1.5¢ a post |
| Answer the direct message from the manager in Austin. | [`Message.schedule`](/code/apps/mailboxes/schedule) | Your account | About 1.5¢ a message |
| Take down yesterday’s post with the wrong number. | [`Post.withdraw`](https://startupbuilder.dev/business/nouns/post/withdraw) | Your account | Free |
| Show me each post’s impressions, replies and reposts this week. | [`Metric.query`](/code/apps/analytics-and-experiments/query) | Your account | Free |

Calls on your own account are free.

Reading this site’s public data needs no account: [`Keyword.search`](/code/data/keywords/search), [`Monitor.create`](/code/data/monitors/create) are Data calls (the [three ways a call runs](/code/integrations#three-ways)).

## What it holds
| Noun | The account’s object | When | Which side leads |
| --- | --- | --- | --- |
| [Post](https://startupbuilder.dev/business/nouns/post) | `post` | Your agent posts or replies | Your records |
| [Message](https://startupbuilder.dev/business/nouns/message) | `dm_event` | Someone writes to you, or your agent answers | The account |
| [Prospect](https://startupbuilder.dev/business/nouns/prospect) | `user` | Someone who fits replies, mentions you or writes to you | Your records |

## Events and webhooks
| Direction | Event |
| --- | --- |
| Emits | `Post.published`, `Post.withdrawn`, `Message.created`, `Prospect.engaged` |
| Hears `account_activity` | Becomes `Message.created` |
| Hears `filtered_stream` | Becomes `Monitor.checked` |

Any Event can wake a Workflow, and a Watch delivers it to your endpoint, signed ([Events and webhooks](/code/events)).

## Limits
| What | Limit | Call |
| --- | --- | --- |
| Each post or reply | X bills 1.5¢ through its API, and 20¢ when the text carries a link; the price shows before the call runs | [`Post.publish`](/code/apps/social/publish) |
| Each direct message | X bills 1.5¢ | [`Message.schedule`](/code/apps/mailboxes/schedule) |
| Monthly spend | Your standing approval holds the month’s X spend; a post past it waits with `over-mandate` | [`Post.publish`](/code/apps/social/publish) |
| Replies to strangers | Only to posts that describe your problem, and never twice in one thread without an answer back | Every call |

## Start here
| Move | The rule |
| --- | --- |
| Structure | One founder account, not a brand account: a bio that names the buyer, a pinned post with the walkthrough, and more replies than posts. |
| Budget | About 20¢ a day: 10 replies to people describing the problem and 3 posts of your own, each 1.5¢ with no link; a link costs 20¢, so it goes only where someone asks for it. |
| Creative | Answer the post in the reply itself, with the steps or the number; name your product only where it is the honest answer, and say it is yours. |
| Kill rule | If 30 replies start no conversation, change which posts you answer (fresher, more specific) before changing the words; stop replying in any thread that turns hostile. |

| Benchmark | Source |
| --- | --- |
| 1.5¢ a post or reply, 20¢ with a link, 1.5¢ a direct message | X API pricing |
| A link counts as 23 of the 280 characters | X developer docs |
| Judge at 30 replies: 3 or more that turn into a direct message or a call | Our planning number |

## Field map
| Our field | X account’s field | Notes | Calls |
| --- | --- | --- | --- |
| `Post.body` | `text` | 280 weighted characters; a link counts as 23 wherever it points | [`Post.publish`](/code/apps/social/publish) |
| `Post.media` | `media.media_ids` | Up to 4 images, or 1 GIF, or 1 video, uploaded first | [`Post.publish`](/code/apps/social/publish) |
| `Post.format` | `reply.in_reply_to_tweet_id` | A thread is a chain of posts, each replying to the last | [`Post.publish`](/code/apps/social/publish) |
| `Message.body` | `text` | None. | [`Message.schedule`](/code/apps/mailboxes/schedule) |

## What try does here
Renders each post at X’s weighted count, with links at 23 characters, and returns the price X would bill; nothing is posted and nothing is billed.

## How long a connection lasts
A connection lasts until you revoke it in X settings: the `offline.access` grant keeps the connection, and the platform renews the two-hour access token on its own.

The platform asks you to reconnect 7 days before it runs out; until you do, a call that needs it refuses with [`needs-reauth`](/code/refusals#needs-reauth).

## Formats
| Site | Format | Size | Limits |
| --- | --- | --- | --- |
| [X](/venues#x) | Standard post | None. | 280 weighted characters; a link counts as 23 and an emoji as 2 |
| [X](/venues#x) | Promoted post | None. | A post already on your account, promoted as it is |

## Plays and strategies
| Kind | Where |
| --- | --- |
| Plays | [Founder voice](/plays/founder-voice), [Engagement bridge](/plays/engagement-bridge), [Launch week](/plays/launch-week), [Organic social](/plays/organic-social), [Community answers](/plays/community-answers), [Build in public](/plays/build-in-public) |
| Strategies | [Hands-on](/strategy/hands-on), [Launch and search](/strategy/launch-and-search) |

## Used by
No Workflow, agent task or Service acts through it yet: your agents call it directly.

## Reference

| Call | Path | Price |
| --- | --- | --- |
| [`Post.publish`](/code/apps/social/publish) | `POST /posts/publish` | About 1.5¢ a post |
| [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | `POST /conversations/answer` | About 1.5¢ a post |
| [`Message.schedule`](/code/apps/mailboxes/schedule) | `POST /messages/schedule` | About 1.5¢ a message |
| [`Post.withdraw`](https://startupbuilder.dev/business/nouns/post/withdraw) | `POST /posts/withdraw` | Free |
| [`Metric.query`](/code/apps/analytics-and-experiments/query) | `POST /metrics/query` | Free |