Search X posts

POST/v1/tools/x.search.posts/callsNeeds an API key

Returns the X posts that match a search, from the top, latest or media tab, with author and engagement counts. Use it to follow the conversation on a topic.

Tool x.search.posts on X (Twitter). Contract version 1, released 2026-10-27.

Over REST, send the input in the body. Over MCP, pass the same input to call_tool.

Both return the full response: the call's ID, status and cost, with this tool's result in output.

Input

querystringRequired

The search query. X matches more than a post's text, such as the post it quotes, a linked article or its media, so a post may not contain the query's words.

tabstring· default top

Which tab of X's search results to read: top (X's ranking), latest or media (posts with photos or videos).

top

latest

media

next_page_tokenstring

Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same query and tab.

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.

idstringRequired

X's identifier of the post. The post is at https://x.com/i/status/ followed by it.

urlstring

Address of the post on x.com.

Format uri.

textstring

What the post says, links written as X's t.co short links.

published_atstring

When the post was published, in ISO 8601.

author_idstring

X's numeric identifier of the author, as a string.

author_usernamestring

The author's handle, without the @.

author_namestring

The author's display name.

author_image_urlstring

Address of the author's profile picture.

author_follower_countinteger

reply_countinteger

repost_countinteger

quote_countinteger

like_countinteger

bookmark_countinteger

view_countinteger

Number of times the post was seen.

conversation_idstring

Identifier of the post that opened the thread; the post's own id when it opened it.

in_reply_to_post_idstring

Identifier of the post this one replies to.

in_reply_to_usernamestring

Handle of the author this post replies to, without the @.

sensitiveboolean

Whether X marks the post as possibly sensitive.

quoted_post_idstring

Identifier of the post this one quotes.

quoted_post_textstring

quoted_post_author_usernamestring

hashtagsarray of string

Each hashtag in the text, without the

mentioned_usernamesarray of string

Handle of each account the text mentions, without the @.

link_urlsarray of string

Full address of each link in the text.

image_urlsarray of string

Address of each photo attached to the post.

videosarray of object

Each video attached to the post.

videos.preview_image_urlstringRequired

Address of the video's still image.

videos.duration_msinteger

Length of the video, in milliseconds.

videos.widthinteger

Width of the original video, in pixels.

videos.heightinteger

Height of the original video, in pixels.

`pagination`

One object. Can be null. How to fetch the next page. Null on the last page.

next_page_tokenstringRequired

Send as next_page_token to fetch the next page.

curl https://api.voxoria.ai/v1/tools/x.search.posts/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"from:OpenAI","tab":"latest"}}'

import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/x.search.posts/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"query": "from:OpenAI", "tab": "latest"}},
    timeout=60,
)
print(response.json())

const response = await fetch("https://api.voxoria.ai/v1/tools/x.search.posts/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"query": "from:OpenAI", "tab": "latest"}}),
});
console.log(await response.json());

{
  "name": "call_tool",
  "arguments": {
    "tool": "x.search.posts",
    "input": {
      "query": "from:OpenAI",
      "tab": "latest"
    }
  }
}

200 OKoutputapplication/json

{
  "posts": [
    {
      "id": "2090885187634905500",
      "url": null,
      "text": "As we continue to push the frontier of capabilities while improving efficiency, we're dropping API and credit pricing of GPT-5.6 Sol by over 20% for the next 3 months. https://t.co/UoTb3hcB2t",
      "published_at": "2026-08-21T19:34:10Z",
      "author_id": "4398626122",
      "author_username": "OpenAI",
      "author_name": "OpenAI",
      "author_image_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg",
      "author_follower_count": 5471705,
      "reply_count": 718,
      "repost_count": 848,
      "quote_count": 610,
      "like_count": 13888,
      "bookmark_count": 1000,
      "view_count": 3898181,
      "conversation_id": "2090885187634905500",
      "in_reply_to_post_id": null,
      "in_reply_to_username": null,
      "sensitive": false,
      "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/amplify_video_thumb/2090884941819285504/img/JpIf7VDQGLhawgzB.jpg",
          "duration_ms": 5000,
          "width": 1536,
          "height": 864
        }
      ]
    },
    {
      "id": "2104986129686741046",
      "url": null,
      "text": "GPT-6.1 Sol: near-Astra intelligence for a fifth of the price.\n\nIt’s the most cost-efficient model for its performance available today. https://t.co/hH8PnE2Oxk",
      "published_at": "2026-09-29T17:26:16Z",
      "author_id": "4398626122",
      "author_username": "OpenAI",
      "author_name": "OpenAI",
      "author_image_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg",
      "author_follower_count": 5471705,
      "reply_count": 721,
      "repost_count": 1713,
      "quote_count": 1082,
      "like_count": 21116,
      "bookmark_count": 1936,
      "view_count": 3238371,
      "conversation_id": "2104986129686741046",
      "in_reply_to_post_id": null,
      "in_reply_to_username": null,
      "sensitive": false,
      "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/amplify_video_thumb/2104984622191067137/img/6xK8vFcs_vBe4SKN.jpg",
          "duration_ms": 8366,
          "width": 1920,
          "height": 1080
        }
      ]
    },
    {
      "id": "2104984504133918973",
      "url": null,
      "text": "Introducing dots, powered by GPT-6 Astra.\n\nRemarkably capable, always-on agents built to handle everything. https://t.co/inY5BZj3Kz",
      "published_at": "2026-09-29T17:19:49Z",
      "author_id": "4398626122",
      "author_username": "OpenAI",
      "author_name": "OpenAI",
      "author_image_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg",
      "author_follower_count": 5471705,
      "reply_count": 2348,
      "repost_count": 3367,
      "quote_count": 3324,
      "like_count": 38099,
      "bookmark_count": 10502,
      "view_count": 14831016,
      "conversation_id": "2104984504133918973",
      "in_reply_to_post_id": null,
      "in_reply_to_username": null,
      "sensitive": false,
      "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/amplify_video_thumb/2104984413113393152/img/ww-kV51l6J5DwxZJ.jpg",
          "duration_ms": 147818,
          "width": 1920,
          "height": 1080
        }
      ]
    }
  ],
  "pagination": {
    "next_page_token": "pt1.dGlraHViOkRBQUNDZ0FDSFZaXzZnZ0FKeEFLQUFNZFZuX3FCX19ZOEFnQUJBQUFBQUlMQUFVQUFBRHdSVzFRUXpaM1FVRkJabEV2WjBkS1RqQjJSM0F2UVVGQlFVSlJZek4yZW5aU1NtRjRTMEowT0hwM0szUXlka0ZaUnpONWRTOVZjV0ZqUldOYVVFSmllV1pLZGtKbWVEQldSRlJzVjIxMlJsVklVRVI2TUcxVFlWRmxTVmh6VFVsb0x6RnZRak40TVZGaWVFWnpiV2xGTkVjdmMwUXdkWGhpUVZKblpGRk1PVlpEUW5SU2FrSXdZbU5hYlRGWGEwZGpTRlJhYjFGUWNXRnZVREJrVTNjNWVHUXhkbEoyUWpGV2JUQjZWRmQxU0hsSVV6RjRTR3RCV0c5VU5HTXJaVVpyUVRWd1VrZFNlV1ZzVGt4cFJtOUVWVWhSVWxKQlFYTmhkMXAzWkU1dGJUZGtVbkJCVG1nd1pVRXlSR2hIZVVKUUNBQUdBQUFBQUFnQUJ3QUFBQUFNQUFnS0FBRVhzTUloXzFvQjN3QUFBQQ"
  }
}

The output of a real call, each list cut to 3 items.