Posts actions
4 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.
Look up a post
Section titled “Look up a post”posts.get · read
Any X post by id or URL with its numbers and context.
- MCP tool:
get_post. Loaded by default in MCP clients. - REST:
GET /v1/posts/get - CLI:
xholic posts get - 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 |
|---|---|---|---|
tweetId |
string | Yes | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Post conversation
Section titled “Post conversation”posts.conversation · read
A post’s thread and replies.
- MCP tool:
posts_conversation. Catalog: reach it withfind_actionsandrun_read_action, or turn on the full toolset. - REST:
GET /v1/posts/conversation - CLI:
xholic posts conversation - 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 |
|---|---|---|---|
tweetId |
string | Yes | |
account |
string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection’s default account. |
Schedule a post
Section titled “Schedule a post”posts.schedule · publish
Schedule a post or thread on X at a time. Supports media and automations. Call it only when the user asked for this in the conversation; never on your own initiative. It spends a post credit when it goes live.
- MCP tool:
schedule_post. Loaded by default in MCP clients. - REST:
POST /v1/posts/schedule - CLI:
xholic posts schedule - Scope:
publish - Plan: Every plan, including the trial
- Cost: Spends a post credit when the post goes live.
- Rate limit bucket:
write - Undo: from the activity log, which runs
queue.unschedule
Input
| Field | Type | Required | Description |
|---|---|---|---|
text |
string ≤ 25000 chars | Yes | |
threadParts |
array of string ≤ 25000 chars (min 2, max 25) | No | For a thread: every part in order, starting with the same first post as text. |
scheduledAt |
string ≤ 40 chars | Yes | When to post: the user’s local date and time such as 2026-10-25T10:00 (then pass timezone), or an ISO time with offset. |
timezone |
string ≤ 80 chars | Yes | IANA timezone such as America/New_York. Use the user’s timezone. |
media |
array of object (max 4) | No | Media from upload_media, by mediaId. Up to 4 images, or 1 GIF or video. |
automation |
object | No | Post automations (auto-repost, auto-plug reply, auto-delete, auto-DM). Shape as in the docs: docs.xholic.ai/api/automations. |
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. |
Post now
Section titled “Post now”posts.publish_now · publish
Post to X immediately. Requires idempotencyKey so a retry can never post twice. Call it only when the user asked for this in the conversation; never on your own initiative. Spends a post credit.
- MCP tool:
publish_now. Loaded by default in MCP clients. - REST:
POST /v1/posts/publish-now - CLI:
xholic posts publish-now - Scope:
publish. Destructive: it can’t be taken back - Plan: Every plan, including the trial
- Cost: Spends a post credit when the post goes live.
- Rate limit bucket:
write
Input
| Field | Type | Required | Description |
|---|---|---|---|
text |
string ≤ 25000 chars | Yes | |
threadParts |
array of string ≤ 25000 chars (min 2, max 25) | No | For a thread: every part in order, starting with the same first post as text. |
media |
array of object (max 4) | No | Media from upload_media, by mediaId. Up to 4 images, or 1 GIF or video. |
automation |
object | No | Post automations (auto-repost, auto-plug reply, auto-delete, auto-DM). Shape as in the docs: docs.xholic.ai/api/automations. |
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. |