search:post

Finds recent posts matching a query, from anywhere on X: roughly the last seven days, newest first. It is the only read that looks outside the account's own connections, and the one most likely to spend money faster than you meant.

Fields
query Required. What to search for, up to 512 characters. X's operators work: from:handle, "a phrase", -is:reply. To leave replies or reposts out, write -is:reply or -is:retweet here: a search takes no include_replies
max how many to return, 10 to 100. This is what the call costs
cursor the next from the page before
since_id, until_id only posts newer, or older, than that id
since_time, until_time the same window in time, ISO 8601 UTC
profile the account to read as. Optional when the agent has one
reason Required over MCP. One short sentence, in the agent's own words, for the person

X will not return fewer than ten

A max below ten is raised to ten before the call leaves, and the answer carries a note saying so, because ten is what X returns and what it bills. Leaving max out prices the call at ten as well.

What comes back

{ "status": "done",
  "ref": "8H3QW1LT",
  "page": { "next": "b26v89c19zqg8o3fpds1",
            "newest_id": "1832000000000000011",
            "oldest_id": "1832000000000000002" },
  "data": {
    "data": [
      { "id": "1832000000000000011",
        "text": "Anyone else seeing this on the new build?",
        "created_at": "2026-09-15T11:02:09.000Z",
        "author_id": "1400000000000000044",
        "edit_history_post_ids": ["1832000000000000011"],
        "lang": "en",
        "public_metrics": {
          "repost_count": 0, "reply_count": 3, "like_count": 5,
          "quote_count": 0, "bookmark_count": 1, "impression_count": 240
        } }
    ],
    "meta": { "result_count": 10,
              "newest_id": "1832000000000000011",
              "oldest_id": "1832000000000000002",
              "next_token": "b26v89c19zqg8o3fpds1" }
  } }

data.data is always an array and may be empty: a query nobody matched is a done with result_count: 0.

The page block is ours, in our words

next goes straight back as cursor, and newest_id goes back as since_id next time so you are not charged twice for a post you already have. Every page is a fresh call at the same price.