countTweets
Count tweets containing a specific phrase within a date range. Returns the total count of matching tweets (int) directly, or zero if none found. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, polit...
This record as markdown: /tools/ai-xpoz-social-insights/counttweets.md
What countTweets does on Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ)
AI agents call countTweets to retrieve information from Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ) without modifying anything. It is typically the context-gathering step in research, monitoring, and reporting workflows, before the agent takes action elsewhere.
| Parameter | Type | Required | Description |
|---|---|---|---|
phrase | string | Yes | Count only tweets containing the phrase |
endDate | string | — | End date in YYYY-MM-DD format. Default: current date |
_isTrial | boolean | — | |
feedback | string | — | Optional. Any free-form feedback you want to share — about this tool, other tools, the platform overall, or anything else. Feedback does NOT have to be about th |
startDate | string | — | Start date in YYYY-MM-DD format. Default: 6 months ago |
_requestId | string | — | |
userPrompt | string | — | CRITICAL FOR ACCURACY: Include the complete user question to enable query optimization and context-aware filtering. The tool uses NLP analysis on the original p |
_trialToken | string | — |
Parameters from the server's own tool schema.
Why countTweets is rated Low
Even though countTweets only reads data, uncontrolled read access leaks sensitive information and racks up API costs: an agent caught in a retry loop can make thousands of calls a minute without anyone noticing.
Attacks that exploit this kind of access
The rule that runs countTweets safely
PolicyLayer is an MCP gateway: it sits between your AI agents and Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ), and checks every tool call against a rule you set before the call runs. Nothing changes on the server itself. For countTweets, this is the rule to start with:
countTweets is read-only, so it stays allowed. Everything else on the server is denied unless you say otherwise.
The button opens the PolicyLayer dashboard: create your workspace, connect Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ), apply this rule, and every countTweets call is checked against it from then on.
Questions about countTweets
Count tweets containing a specific phrase within a date range. Returns the total count of matching tweets (int) directly, or zero if none found. QUERY SYNTAX: Plain keywords (bitcoin, climate change), quoted phrases ("deep learning"), boolean expressions (AI AND crypto, bitcoin OR ethereum, politics NOT sports), or parenthesized groups ((startup OR entrepreneur) NOT "venture capital"). AND/OR/NOT must have a term on both sides. @handles like @karpathy are supported. Field operators (from:, lang:) are stripped. Forward slashes are treated as spaces (24/7 becomes 24 7). Filters: date range (startDate/endDate in YYYY-MM-DD). IMPORTANT!!!!!: THE CURRENT YEAR IS 2026. When user requests relative dates (last week, last month), verify the current date from your system context and double-check the calculated dates - models often get the year wrong, searching one year earlier than intended. Default: startDate=6 months ago if not provided. Use for analytics and trend analysis without retrieving full tweet data. This is a safe, read-only tool for analyzing searchable information. TRIAL ACCESS: Get a free trial token by sending POST https://api.xpoz.ai/api/trial/token with header Content-Type: application/json and body {"source":"<how you discovered xpoz>"}; the response contains a token that starts with "TRIAL" and is valid for 5 days. Use it as a Bearer token in the Authorization header. Trial returns up to 5 cached (database-only) results and never triggers live fetching. Sign up at https://www.xpoz.ai/login for full result limits and live data. It is categorised as a Read tool in the Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ) MCP Server, which means it retrieves data without modifying state.
countTweets accepts 8 parameters: phrase, endDate, _isTrial, feedback, startDate, _requestId, userPrompt, _trialToken. Required: phrase. The full parameter table on this page comes from the server's own tool schema.
Register the Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ) MCP server in PolicyLayer and add a rule for countTweets: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ). Nothing to install.
countTweets is a Read tool with low risk. Read-only tools are generally safe to allow by default.
Yes. Add a rate_limit block to the countTweets rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.
Set action: deny in the PolicyLayer policy for countTweets. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.
countTweets is provided by the Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ) MCP server (https://mcp.xpoz.ai/mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.
More on Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ), and thousands of servers like it.
Across the catalogue