Engage actions
12 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.
Who to engage now
Section titled “Who to engage now”engage.who_to_engage · read
People worth replying to right now and why: unanswered mentions, the account’s reply circle, and warm Signals leads. Write the replies yourself in the user’s voice (get_me), then post with schedule_post or publish_now using replyTo only if the user asks.
- MCP tool:
who_to_engage. Loaded by default in MCP clients. - REST:
GET /v1/engage/who-to-engage - CLI:
xholic engage who-to-engage - Scope:
read - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
limit |
integer 1–30 | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Reply circle
Section titled “Reply circle”engage.reply_circle · read
The people the account trades replies with most, and who to reply to next to grow.
- MCP tool:
engage_reply_circle. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/engage/reply-circle - CLI:
xholic engage reply-circle - Scope:
read - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
limit |
integer 1–10 | No | Fresh posts to return. Default: 5. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Engage guidelines status
Section titled “Engage guidelines status”engage.get_consent · read
Whether the user accepted Engage’s guidelines. Engage feeds, mentions and replies need it; until then they answer with a consent error.
- MCP tool:
engage_get_consent. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/engage/get-consent - CLI:
xholic engage get-consent - Scope:
read - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
read
Input
No input.
Accept Engage guidelines
Section titled “Accept Engage guidelines”engage.accept_consent · write
Record that the user accepted Engage’s guidelines for engaging on X. Tell the user they are accepting them and call it only after they explicitly agree in the conversation; never on your own initiative.
- MCP tool:
engage_accept_consent. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/accept-consent - CLI:
xholic engage accept-consent - Scope:
write - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
version |
“v2” | Yes | |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Engage feeds
Section titled “Engage feeds”engage.list_feeds · read
The account’s saved Engage feeds (FEEDS) or extension timelines (TIMELINE).
- MCP tool:
engage_list_feeds. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/engage/list-feeds - CLI:
xholic engage list-feeds - Scope:
read - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
read
Input
| Field | Type | Required | Description |
|---|---|---|---|
placement |
“FEEDS” \ | “TIMELINE” | No |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Create an Engage feed
Section titled “Create an Engage feed”engage.create_feed · write
Save a feed of posts to engage with: a topic, a contact list, an X list, or one account (timelines only). Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
engage_create_feed. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/create-feed - CLI:
xholic engage create-feed - Scope:
write - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write - Undo: from the activity log, which runs
engage.delete_feed
Input
| Field | Type | Required | Description |
|---|---|---|---|
name |
string ≤ 80 chars | Yes | |
type |
“TOPIC” \ | “FOLLOWING” \ | “CONTACT_LIST” \ |
placement |
“FEEDS” \ | “TIMELINE” | No |
query |
string ≤ 500 chars or null | No | |
contactListId |
string (uuid) or null | No | |
xListId |
string or null | No | |
excludedHandles |
array of string ≤ 16 chars (max 50) | No | |
excludedTerms |
array of string ≤ 80 chars (max 50) | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Create several Engage feeds
Section titled “Create several Engage feeds”engage.create_feeds · write
Save up to 8 Engage feeds in one call. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
engage_create_feeds. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/create-feeds - CLI:
xholic engage create-feeds - Scope:
write - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
feeds |
array of object (min 1, max 8) | Yes | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Edit an Engage feed
Section titled “Edit an Engage feed”engage.update_feed · write
Change a saved feed. Send the whole feed (name, type, query…); placement can’t change. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
engage_update_feed. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/update-feed - CLI:
xholic engage update-feed - Scope:
write - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Feed id from engage.list_feeds. |
name |
string ≤ 80 chars | Yes | |
type |
“TOPIC” \ | “FOLLOWING” \ | “CONTACT_LIST” \ |
placement |
“FEEDS” \ | “TIMELINE” | No |
query |
string ≤ 500 chars or null | No | |
contactListId |
string (uuid) or null | No | |
xListId |
string or null | No | |
excludedHandles |
array of string ≤ 16 chars (max 50) | No | |
excludedTerms |
array of string ≤ 80 chars (max 50) | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Delete an Engage feed
Section titled “Delete an Engage feed”engage.delete_feed · write
Delete a saved Engage feed. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
engage_delete_feed. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/delete-feed - CLI:
xholic engage delete-feed - Scope:
write. Destructive: it can’t be taken back - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | Yes | Feed id from engage.list_feeds. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Read an Engage feed
Section titled “Read an Engage feed”engage.feed · read
Posts to engage with from a saved feed (feedId) or an ad-hoc topic search (type TOPIC + query), top or latest. Posts the user already replied to are hidden by default.
- MCP tool:
engage_feed. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/engage/feed - CLI:
xholic engage feed - Scope:
read - Plan: Every plan, including the trial
- Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
- Rate limit bucket:
live_x
Input
| Field | Type | Required | Description |
|---|---|---|---|
feedId |
string (uuid) | No | |
type |
“TOPIC” \ | “FOLLOWING” \ | “CONTACT_LIST” \ |
query |
string ≤ 500 chars | No | |
sort |
“TOP” \ | “LATEST” | No |
cursor |
string ≤ 2000 chars | No | From the previous page, for more. |
hideReplied |
boolean | No | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Hide or mark a post replied
Section titled “Hide or mark a post replied”engage.set_item_state · write
Hide a post from Engage feeds (a skip), or mark it replied or not replied.
- MCP tool:
engage_set_item_state. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/set-item-state - CLI:
xholic engage set-item-state - Scope:
write - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
tweetId |
string | Yes | X post id (digits). |
hidden |
boolean | No | |
replied |
boolean | No | |
accountId |
string | No | The post author’s X user id, when known. |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |
Clear hidden posts
Section titled “Clear hidden posts”engage.clear_skips · write
Bring back every post the account hid from Engage feeds. Call it only when the user asked for this in the conversation; never on your own initiative.
- MCP tool:
engage_clear_skips. Catalog: reach it withfind_actionsandrun_write_action, or turn on the full toolset. - REST:
POST /v1/engage/clear-skips - CLI:
xholic engage clear-skips - Scope:
write - Plan: Every plan, including the trial
- Cost: Free.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
dryRun |
boolean | No | Return exactly what would happen without doing it. |
idempotencyKey |
string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |