# List an X user's recent posts Returns an X user's recent posts, with engagement counts, a page at a time. Use it to follow an account. Tool `x.user.posts` on X (Twitter). Contract version 1, released 2026-10-27. ## Example call Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`. cURL: ```bash curl https://api.voxoria.ai/v1/tools/x.user.posts/calls \ -H "Authorization: Bearer $VOXORIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input":{"username":"OpenAI"}}' ``` Python: ```python import os import httpx response = httpx.post( "https://api.voxoria.ai/v1/tools/x.user.posts/calls", headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"}, json={"input": {"username": "OpenAI"}}, timeout=60, ) print(response.json()) ``` TypeScript: ```ts const response = await fetch("https://api.voxoria.ai/v1/tools/x.user.posts/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"input": {"username": "OpenAI"}}), }); console.log(await response.json()); ``` MCP (`tools/call` params): ```json { "name": "call_tool", "arguments": { "tool": "x.user.posts", "input": { "username": "OpenAI" } } } ``` Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`. ## Input | Input | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `username` | string | Yes | | The user's handle, without the @. | | `next_page_token` | string | No | | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same username. | ## Output A successful call returns these blocks in its `output`. A field not marked required can be `null`. ### posts A list of rows. Always present, possibly empty. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | X's identifier of the post. The post is at https://x.com/i/status/ followed by it. | | `url` | string | No | Address of the post on x.com. Format `uri`. | | `text` | string | No | What the post says, links written as X's t.co short links. | | `published_at` | string | No | When the post was published, in ISO 8601. | | `author_id` | string | No | X's numeric identifier of the author, as a string. | | `author_username` | string | No | The author's handle, without the @. | | `author_name` | string | No | The author's display name. | | `author_image_url` | string | No | Address of the author's profile picture. | | `author_verified` | boolean | No | Whether X marks the author as verified. | | `author_follower_count` | integer | No | | | `reply_count` | integer | No | | | `repost_count` | integer | No | | | `quote_count` | integer | No | | | `like_count` | integer | No | | | `bookmark_count` | integer | No | | | `view_count` | integer | No | Number of times the post was seen. | | `conversation_id` | string | No | Identifier of the post that opened the thread; the post's own id when it opened it. | | `in_reply_to_post_id` | string | No | Identifier of the post this one replies to. | | `in_reply_to_username` | string | No | Handle of the author this post replies to, without the @. | | `sensitive` | boolean | No | Whether X marks the post as possibly sensitive. | | `reposted_post_id` | string | No | Identifier of the post this one reposts. A repost's text and counts are X's for the repost, which may cut the original's text short. | | `quoted_post_id` | string | No | Identifier of the post this one quotes. | | `quoted_post_text` | string | No | | | `quoted_post_author_username` | string | No | | | `hashtags` | array of string | No | Each hashtag in the text, without the | | `mentioned_usernames` | array of string | No | Handle of each account the text mentions, without the @. | | `link_urls` | array of string | No | Full address of each link in the text. | | `image_urls` | array of string | No | Address of each photo attached to the post. | | `videos` | array of object | No | Each video attached to the post. | | `videos.preview_image_url` | string | Yes | Address of the video's still image. | | `videos.duration_ms` | integer | No | Length of the video, in milliseconds. | | `videos.width` | integer | No | Width of the original video, in pixels. | | `videos.height` | integer | No | Height of the original video, in pixels. | ### pagination One object. Can be `null`. How to fetch the next page. Null on the last page. | Field | Type | Required | Description | | --- | --- | --- | --- | | `next_page_token` | string | Yes | Send as next_page_token to fetch the next page. | ## Example output The `output` of a real call, each list cut to 3 items. ```json { "posts": [ { "id": "2115237121300770818", "url": null, "text": "RT @KITP_UCSB: Statement of Yang-Mills Working Group, a scientific collaboration to interpret AI result related to the existence of quantum…", "published_at": "2026-10-28T00:20:03Z", "author_id": "4398626122", "author_username": "OpenAI", "author_name": "OpenAI", "author_image_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg", "author_verified": true, "author_follower_count": 5484617, "reply_count": 0, "repost_count": 102, "quote_count": 0, "like_count": 0, "bookmark_count": 0, "view_count": 33101, "conversation_id": "2115237121300770818", "in_reply_to_post_id": null, "in_reply_to_username": null, "sensitive": null, "reposted_post_id": "2115236165330846045", "quoted_post_id": null, "quoted_post_text": null, "quoted_post_author_username": null, "hashtags": null, "mentioned_usernames": [ "KITP_UCSB" ], "link_urls": null, "image_urls": null, "videos": null }, { "id": "2114833781815456118", "url": null, "text": "RT @danintheory: We are announcing three new discoveries in mathematics, computer science, and physics about harmonic analysis, complexity…", "published_at": "2026-10-26T21:37:19Z", "author_id": "4398626122", "author_username": "OpenAI", "author_name": "OpenAI", "author_image_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg", "author_verified": true, "author_follower_count": 5484617, "reply_count": 0, "repost_count": 1072, "quote_count": 0, "like_count": 0, "bookmark_count": 0, "view_count": 48860, "conversation_id": "2114833781815456118", "in_reply_to_post_id": null, "in_reply_to_username": null, "sensitive": null, "reposted_post_id": "2114833682469122314", "quoted_post_id": null, "quoted_post_text": null, "quoted_post_author_username": null, "hashtags": null, "mentioned_usernames": [ "danintheory" ], "link_urls": null, "image_urls": null, "videos": null }, { "id": "2114780711664398349", "url": null, "text": "GPT-6.1 Terra: delivering fast and capable computer use at a lower price.\n\nGPT-6.1 Terra understands what’s on screen, takes action across apps, writes naturally, and is a more capable model for your whole workday with the efficiency to take on more of it. https://t.co/8JTN1yonmV", "published_at": "2026-10-26T18:06:27Z", "author_id": "4398626122", "author_username": "OpenAI", "author_name": "OpenAI", "author_image_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg", "author_verified": true, "author_follower_count": 5484617, "reply_count": 1573, "repost_count": 2418, "quote_count": 2177, "like_count": 27262, "bookmark_count": 4244, "view_count": 5971781, "conversation_id": "2114780711664398349", "in_reply_to_post_id": null, "in_reply_to_username": null, "sensitive": false, "reposted_post_id": null, "quoted_post_id": null, "quoted_post_text": null, "quoted_post_author_username": null, "hashtags": null, "mentioned_usernames": null, "link_urls": null, "image_urls": null, "videos": [ { "preview_image_url": "https://pbs.twimg.com/media/HVk3m2pW0AERTJj.jpg", "duration_ms": 31458, "width": 1920, "height": 1080 } ] } ], "pagination": { "next_page_token": "pt1.dGlraHViOkRBQUhDZ0FCSFZzTklkdV9fLThMQUFJQUFBQVRNakV4TVRFNE5UVXdORGMwTmpJeE16Y3dOUWdBQXdBQUFBSUFBQQ" } } ```