Search
Tool ID: x_search
Summary
Finds posts that match words and filters. Read-only. The default window is about the last 7 days, 10 posts, newest match first. This is not the Top or News tab in the X app.
When to use it
- You want posts about a topic, tag, or link.
- You want posts from one @handle, or replies to them.
- You want a narrower slice: language, verified accounts, links, or media.
What you need
| Requirement | Required? |
|---|---|
| Metraclick connection | Yes |
| Tool enabled for your account | Yes |
| X account connected by an administrator | Yes |
Parameters
| Parameter | Required? | Description |
|---|---|---|
query |
One filter or this | Words and X operators (from:, #tag, url:, -is:reply, and similar). |
hashtag |
No | One tag, with or without #. |
cashtag |
No | One ticker, with or without $. |
from_user |
No | Author @handle. |
to_user |
No | Account being replied to. |
lang |
No | Language, for example en. |
since / until |
No | YYYY-MM-DD or a full timestamp. |
exclude_replies |
No | Hide replies. |
exclude_reposts |
No | Hide reposts. |
verified_only |
No | Only verified accounts. |
has_links |
No | Only posts that contain a link. |
has_media |
No | Only posts with media. |
media_type |
No | images, videos, or media. |
conversation_id |
No | Stay inside one thread. For replies, List replies is simpler. |
archive |
No | Search the full history when the API plan allows it. |
max_results |
No | 10–100. Default 10. Smaller numbers are raised to 10. |
pagination_token |
No | next_token from the previous page. |
Filters are combined. You need at least a query or one filter.
What you get back
The exact query that was sent, the posts (same shape as Get post), and next_token when more results exist. Topic labels show up as annotations when X includes them.
Example prompts
Search X for posts about "metraclick" from the last week, English only, no reposts.
Find recent posts with the hashtag ProductLaunch that include a link.
What has @example posted that mentions pricing since Monday?
Tips
- There is no separate news search. For news-like results, ask for a tag or keywords plus links, a language, and verified accounts.
- Full archive search can fail if the API plan does not include it. The recent search still works.
- To open one result, pass its link to Get post.
- Posts that mention you, including replies and quotes, come from Mentions. A search for the @handle misses some of those and costs more.