read:home

Reads the account's home timeline - the accounts it follows, newest first - which is what a person would see on opening X as that account. Only the account being acted as: another account's home is a 403 at X.

Fields
max how many to return, 1 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
include_replies, include_reposts send false to leave replies, or reposts, out of the page. Left out, everything comes back
profile whose home. Optional when the agent has one account
reason Required over MCP. One short sentence, in the agent's own words, for the person

Always send max

Leave it out and the estimate is written against a hundred posts, because that is X's default page here - $0.500 off a cap that starts at $1. This is one of the two reads where forgetting max is a real bill; search:user is the other.

What comes back

{ "status": "done",
  "ref": "6F0MXA3B",
  "page": { "next": "7140w5gefhslx3",
            "newest_id": "1832000000000000090",
            "oldest_id": "1832000000000000061" },
  "data": {
    "data": [
      { "id": "1832000000000000090",
        "text": "The thing nobody tells you about rate limits...",
        "created_at": "2026-09-15T18:22:31.000Z",
        "author_id": "1400000000000000077",
        "conversation_id": "1832000000000000090",
        "edit_history_post_ids": ["1832000000000000090"],
        "lang": "en",
        "public_metrics": {
          "repost_count": 30, "reply_count": 12, "like_count": 204,
          "quote_count": 6, "bookmark_count": 44, "impression_count": 18900
        } }
    ],
    "meta": { "result_count": 10,
              "newest_id": "1832000000000000090",
              "oldest_id": "1832000000000000061",
              "next_token": "7140w5gefhslx3" }
  } }

Every post carries an author_id and no author: Okaybot sends no expansions, because an expansion is another charged resource at X. Putting names to the ids is read:users at $0.010 each, worth doing for the handful you care about.

Sweep, do not page

Keep the newest_id from each answer and send it back as since_id next time. Paging backwards through a home timeline costs the same on every page and buys posts nobody asked for.