search:user

Finds accounts matching a query. X's people search: use it to find an account you know by name but not by handle, and then keep the id.

Fields
query Required. What to search for
max how many to return. This is what the call costs
cursor the next from the page before
profile the account to search as. Optional when the agent has one
reason Required over MCP. One short sentence, in the agent's own words, for the person

Always send max

X's default page here is a hundred accounts, which is $1.000, and the endpoint will take a max as high as a thousand - ten dollars in one call. There is no read on the surface where the number matters more.

It narrows by nothing else

No since_id, no until_id, no time window: X does not offer them on this endpoint, so they are not on the operation and sending one is refused with the reason.

What comes back

{ "status": "done",
  "ref": "J2RN6VC4",
  "page": { "next": "c47f0a1b9de" },
  "data": {
    "data": [
      { "id": "1400000000000000044",
        "name": "Playground User",
        "username": "playground_user",
        "description": "Default playground user for testing API endpoints.",
        "protected": false,
        "verified": false,
        "verified_type": "none",
        "public_metrics": {
          "followers_count": 18, "following_count": 23, "tweet_count": 67,
          "listed_count": 10, "like_count": 109, "media_count": 16
        } }
    ],
    "meta": { "result_count": 10,
              "next_token": "c47f0a1b9de" }
  } }

The page block is shorter here: newest_id and oldest_id are post ids and mean nothing on a list of people, so a user search carries only next and previous. Each page is its own call at the same price.