TrendsAGI

TrendsAGI

[PyPI Version] [npm Version] [Python Versions] [License: MIT]

Real-time trend intelligence for your code and your AI agents: what is trending on social platforms right now, with measured volume, velocity and growth, AI insights on why each topic is moving, evidence-backed recommendations, crisis alerts and watchlists. Paid media and growth teams use it to target what is rising, time spend to the trend curve and brief creative on measured demand.

Install

pip install trendsagi            # client, agent tools and the trendsagi commandpip install "trendsagi[mcp]"     # adds the local MCP server (Python 3.10+)pipx install trendsagi           # just the command line, in its own environmentnpx trendsagi --help             # or the same command line from npm (Node.js 18+)

Create an API key under Profile > API Keys at app.trendsagi.com and export it:

export TRENDSAGI_API_KEY="your_api_key"

Quickstart

import osfrom trendsagi import TrendsAGIClient
client = TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"])
# Fastest-moving Technology topics right nowtrends = client.get_trends(category="Technology", sort_by="velocity", limit=5)for trend in trends.trends:    print(trend.id, trend.name, trend.volume)
# Why is the top one moving?insight = client.get_ai_insights(trends.trends[0].id)if insight:    print(insight.sentiment_summary, insight.key_themes)

Command line

trendsagi login                  # paste an API key; saved to ~/.config/trendsagi/config.jsontrendsagi trends list --category Technology --sort velocity --limit 10trendsagi insights get 123       # audience, sentiment and marketing anglestrendsagi sql "SELECT category, count(*) FROM trends GROUP BY 1 ORDER BY 2 DESC"trendsagi recommendations list --priority hightrendsagi watchlist add "oat milk" --threshold 50000 --emailtrendsagi api /api/integrations/delivery/health -q lookback_hours=24   # any endpoint

Every command has --help. In a terminal, lists print as tables; piped or with --json they print JSON, so trendsagi trends list | jq works. The key comes from --api-key, then TRENDSAGI_API_KEY, then the saved login. Commands that delete something or change live ads ask first; pass --yes in scripts. Exit codes: 0 success, 1 API error, 2 invalid usage, 4 missing or rejected key.

The commands are declared once in src/trendsagi/cli_spec.json; a dependency-free Node.js build of the same CLI lives in npm/ and is published as trendsagi on npm. Guide: trendsagi.com/api-docs/integrations/cli.

The client calls any endpoint too: client.request("GET", "/api/integrations/delivery/health", params={"lookback_hours": 24}).

Use TrendsAGI in your AI assistant (no install)

Add the hosted MCP server, sign in to TrendsAGI and approve the connection:

https://api.trendsagi.com/mcp

Then ask "What is accelerating fastest in Technology this week, and who should I target with it?" The hosted tools are read-only, and each call counts as one API request. Each connection gets its own key, listed as "AI connector: " under Profile > API Keys; delete it to disconnect. Clients without OAuth can send an API key as Authorization: Bearer <key>. Guide: trendsagi.com/mcp.

The hosted server also publishes the TrendsAGI paid-media skill over MCP (SEP-2640) at skill://trendsagi/SKILL.md. Clients that support the io.modelcontextprotocol/skills extension discover it with skills/list and load it with resources/read; the manifest carries a SHA-256 digest and byte size for every file. Clients without the extension still receive the server instructions and tool descriptions, and the plugin distributions keep a bundled copy of the skill.

Build an agent with Cursor Agent SDK

Agent SDK defines agents as a folder of Markdown and TypeScript. Add TrendsAGI with one file and the agent gets the hosted MCP server's read-only tools by name:

// bot/mcp-connections/trendsagi.tsimport { defineConnection } from "@grok/agent-sdk/connections";
export default defineConnection({  url: "https://api.trendsagi.com/mcp",  headers: { authorization: "Bearer ${TRENDSAGI_API_KEY}" },  // filled by Agent SDK, not JavaScript  advertiseTools: true,  effects: "read",});

agent-sdk run --dir . --message "What is rising fastest in Technology this week?"

agent-sdk/ is a complete project to copy: instructions, a trend-brief skill, hosting settings (egress to api.trendsagi.com, a TRENDSAGI_API_KEY secret) and smoke evals. Guide: trendsagi.com/api-docs/integrations/agent-sdk.

Use TrendsAGI from your browser's agent (WebMCP)

WebMCP lets a web page hand tools to the AI agent built into the browser (Chrome and Edge in origin trials, ChatGPT desktop, Brave Leo). While you are signed in to app.trendsagi.com, the app registers TrendsAGI's read-only tools with document.modelContext, so the agent uses them with your session: no connector or API key, and calls count as app use rather than API usage. trendsagi.com offers public tools (docs search, trend reports, plans and the free calculators) to every visitor.

To put TrendsAGI tools on your own site, register them in your page and run them on your server, which keeps the API key:

tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))
tools.webmcp()                     # serve to your page: name, title, description, inputSchema, annotationstools.call("list_trends", args)    # run the call your page forwards

webmcp/ has the browser module and a FastAPI server. Guide: trendsagi.com/webmcp.

Agent tools

One registry, every format. The tools are read-only by default; add_to_watchlist and update_recommendation appear only with allow_writes=True (or trendsagi mcp --allow-writes).

OpenAI

import json, osfrom openai import OpenAIfrom trendsagi import TrendsAGIClient, TrendsAGITools
tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))openai = OpenAI()messages = [{"role": "user", "content": "Find a fast-rising Technology trend and suggest a campaign angle."}]
while True:    reply = openai.chat.completions.create(model="gpt-5-mini", messages=messages, tools=tools.openai())    message = reply.choices[0].message    messages.append(message)    if not message.tool_calls:        print(message.content)        break    for call in message.tool_calls:        result = tools.call(call.function.name, call.function.arguments)        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

Claude, LangChain and others

tools.anthropic()         # Anthropic Messages API tools=tools.openai_responses()  # OpenAI Responses API tools=tools.langchain()         # LangChain StructuredTools (pip install "trendsagi[langchain]")tools.webmcp()            # WebMCP descriptors for document.modelContext.registerTool

With Claude, pass tools=tools.anthropic() and answer each tool_use block with {"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(tools.call(block.name, block.input))}. tools.call never raises: errors come back as {"error": ...} so the model can read a rate limit or a bad argument and recover.

Local MCP server

pip install "trendsagi[mcp]"claude mcp add trendsagi --env TRENDSAGI_API_KEY=your_api_key -- trendsagi mcp

Or in any MCP client's JSON config (Claude Desktop, Cursor, VS Code):

{ "mcpServers": { "trendsagi": { "command": "trendsagi-mcp", "env": { "TRENDSAGI_API_KEY": "your_api_key" } } } }

The local server publishes the same skill as the hosted endpoint, at skill://trendsagi/SKILL.md, and declares the io.modelcontextprotocol/skills extension. It is read from the installed package, so it stays in step with the version of trendsagi you installed. Supporting references cover the tool surface, paid-media workflow, read-only SQL and error handling.

Query with SQL

For answers no single endpoint returns, such as growth by category or the trends that match a watchlist:

schema = client.get_data_schema()   # tables, columns, rules, examplesresult = client.execute_sql(    """    SELECT category, count(*) AS trends, round(avg(growth_pct)::numeric, 1) AS avg_growth_pct    FROM trends    WHERE last_seen_at > now() - interval '7 days' AND growth_pct IS NOT NULL    GROUP BY category ORDER BY avg_growth_pct DESC    """,    max_rows=20,)print(result["columns"], result["rows"])

Tables: trends, trend_snapshots (90 days of readings), trend_categories, trend_insights, watchlist, recommendations and crisis_events; the last three only contain your own account's rows. Queries are one validated SELECT, run read-only for at most 5 seconds, and count as one API request. A refused query raises exceptions.QueryError with a code (such as unknown_table or timeout), plus hint and position when known.

Recommendations with decision briefs

recommendations = client.get_recommendations(match_user_interests=True, priority="high", sort="priority", limit=10)for rec in recommendations.recommendations:    brief = rec.decision_brief    if brief and brief.actionable:        print(rec.title, brief.why_now, brief.next_steps[:1])

Each brief explains why an action is timely, the measured signals behind it and concrete next steps. Its confidence score measures evidence completeness, not the chance of success; use actionable and data_quality to hold back when signals are stale or incomplete.

Ad execution in your own infrastructure

GoogleAdsExecutor, MetaAdsExecutor, TikTokAdsExecutor and LinkedInAdsExecutor take credentials at runtime, use deterministic idempotency keys, and support dry-run previews and strict validation:

from trendsagi.integrations import GoogleAdsExecutor
insight = client.get_ai_insights(trend_id)  # the trend you decided to act ongoogle = GoogleAdsExecutor({    "access_token": os.environ["GOOGLE_ADS_ACCESS_TOKEN"],    "developer_token": os.environ["GOOGLE_ADS_DEVELOPER_TOKEN"],})# Positive keywords target an ad group; campaign criteria can only exclude.preview = google.apply_targeting(    insight,    customer_id="1234567890",    campaign_id="9876543210",    ad_group_id="1122334455",    dry_run=True,    strict_mode=True,)print(preview.response)  # inspect before any real change

See INTEGRATIONS_BYOC.md for every executor.

Errors

from trendsagi import exceptions
try:    client.get_trends(limit=5)except exceptions.RateLimitError:    ...  # back off and retryexcept exceptions.AuthenticationError:    ...  # invalid or revoked key

Other commands

trendsagi mcp [--allow-writes]                              # MCP server over stdiotrendsagi scaffold --type docker --output-dir ./runner      # executor runner templatetrendsagi scaffold --type terraform --output-dir ./infra    # infrastructure template

Plans and limits

The free Developer plan includes one API key and 100 API calls a day; Advantage, Scale and Enterprise raise the daily limit and add keys and team features. Calls above the daily allowance are billed as overage. See pricing.

Links

• API documentation and endpoint reference
• CLI guide
• MCP server guide and WebMCP guide
• Changelog
• Support: trendsagi.com/contact or [email protected]

License

MIT. See LICENSE.