Explore channels and use cases.
TRENDS API / V3 / REST + MCP
Research any topic. Inspect the evidence.
Ask what is trending across the shared index or in your niche, through REST or MCP. Every trend carries its source, dates, measurements and coverage, and states what remains unknown. The legacy v1 API is documented at the end of this page.
QUICKSTART / V3
Your first result in five steps
From a new account to a saved result and a connected agent. The first query costs at most 1 credit, from the free credits a verified account receives; reading it again is free. The commands run in bash or zsh with curl.
Create a free account. Sign in at the dashboard; your first sign-in creates the account. Claim the free credits it offers before you create a key: a verified account receives 100 credits once, then 50 every month. Neither step spends credits or starts research.
Create an API key. In API keys, create a key and keep the default permission, “Read and request trend research”. The key grants
trends:read,trends:queryandcredits:read, works for one workspace, expires after 90 days and is shown once. Load it into your terminal without printing it or saving it in shell history:printf "TrendsFast API key: "; read -rs TRENDSFAST_API_KEY; echo; export TRENDSFAST_API_KEYMake your first query. Global is the cheapest query: it costs at most 1 credit and needs no brand context. Every query carries a
request_idyou generate and keep, and amax_creditsceiling the API requires. If the quote is higher than the ceiling, the API answers 402 and charges nothing. A result with no trends costs 0 credits.REQUEST_ID=$(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())') curl -sS https://trendsfast.com/v3/trends/global \ -H "Authorization: Bearer $TRENDSFAST_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<EOF { "request_id": "$REQUEST_ID", "max_credits": 1, "input": { "lookback_hours": 72, "limit": 5 } } EOFThe first line makes the request ID with
uuidgen, or with Python whereuuidgenis missing. Keep the terminal open: the next step reads the same$REQUEST_ID.Read it again for free. The same request ID returns the saved result, with
usage.this_request_creditsat 0. It is also how you recover a lost response: read the ID you kept rather than sending a new one, which would be a new query.curl -sS https://trendsfast.com/v3/trends/requests/$REQUEST_ID \ -H "Authorization: Bearer $TRENDSFAST_API_KEY"Later, read it by the
result_idin the response atGET /v3/trends/results/{result_id}, and pass?cursor=with itsnext_cursorfor the next page. Reads, pagination and recovery cost 0 credits.Connect your agent. The same key is the bearer token for the MCP server at
https://trendsfast.com/api/mcp/v3, whose 9 tools share the scopes and credit balance above. Once you have a key, API keys shows the exact setup for Claude Code, Claude app, Codex, Cursor, VS Code, Grok Build, ChatGPT, Grok, Grok Bot, OpenClaw and REST (curl); agent setup lists the same commands. Claude, ChatGPT, Grok, Grok Bot, Claude Code, Cursor and VS Code can sign in with OAuth instead of taking a key.Endpoint: https://trendsfast.com/api/mcp/v3 Transport: Streamable HTTP Auth: Bearer token from TRENDSFAST_API_KEY
TRENDS API / V3 / DEVELOPER DOCS
Connect once. Ask what is trending.
Account → scoped key → MCP or REST → one bounded query → free rereads.
- Create your free account. A verified account receives 100 free credits once, then 50 every month. Global questions need no brand context; adding your brand lets niche queries rank evidence against it.
- Create a key in API keys. It is shown once and is scoped to one workspace with
trends:query,trends:readandcredits:read. Keep it inTRENDSFAST_API_KEYin your client’s environment, never in chat, URLs or command arguments. - Add the remote MCP server
https://trendsfast.com/api/mcp/v3with that key as a bearer token, or call REST under/v3/trends. Both share one service, one set of scopes and one credit balance. - Ask one bounded question. Every query carries a
request_idUUID you keep and amax_creditsceiling. A Global query costs at most 1 credit, Niche 3 credits, Ask 5 credits. Empty results cost nothing. - Reread the saved result free until its
expires_at: up to 30 days, sooner when a source’s terms end it. Reads, pagination and recovering a lost response by itsrequest_idcost 0 credits and never start new research. After it, a read answersRESULT_EXPIRED; the query runs again under a newrequest_id, at its price.
| Tool | Cost | What it does |
|---|---|---|
trendsfast_discover_trends | 5 credits | One question across global, core and adjacent scope and every channel. |
trendsfast_global_trends | 1 credit | What is trending across the shared index. No brand context needed. |
trendsfast_niche_trends | 35 credits | Trends ranked against your niche. Name a product to collect your brand's sources fresh first. |
trendsfast_ask_trends | 5 credits | One bounded question, answered from saved evidence. |
trendsfast_video_outlier | 5 credits | One TikTok, Instagram or YouTube video against its creator's recent posts. Charged only when found. |
trendsfast_read_result | free | Reread or page through a saved result, or recover a lost response. |
trendsfast_community_brief | free | Read before drafting for a subreddit, free: its people, how to sound, the winning post and reply, its rules. |
trendsfast_project_context | free | The connected brand and its confirmed niche context. |
trendsfast_credit_balance | free | The credit balance shared by the dashboard, REST and MCP. |
- What does my agent receive?
- Trends with their evidence: the original source URL, publication and observation dates, the signal, any measured growth, the platform, and what coverage was and was not available. Ask answers also show how the question was interpreted. Your agent decides what to write or build with it.
- Which sources are behind it?
- Search, AI search, community and video sources, each with its own status on the sources page. A channel with no permitted observation is reported as unavailable, not as an empty trend list, so “nothing is trending” and “we cannot see there” never look the same.
- Which clients work?
- Any client that speaks Streamable HTTP MCP with a bearer token. Claude, ChatGPT, Grok, Grok Bot, Claude Code, Cursor and VS Code can connect with OAuth instead of a key. See agent setup for each client’s exact command.
- What happens after a lost response?
- Keep the same
request_idand read/v3/trends/requests/{request_id}once before deciding anything. A missing response does not mean nothing was debited, and a new identity is a new billable query. - Existing v1 and v2 integrations
/v1,/api/mcpand the Marketing v2 MCP at/api/mcp/v2are still served for clients built on them, with their own keys and contracts. New connections use V3. See the v1 OpenAPI.- What stays under your control?
- Every query is explicit and capped by your
max_credits. TrendsFast never posts, schedules or publishes anything; it returns evidence, and you or your agent decide what to do with it.
TRENDSFAST_API_KEY=<your key> # set in the client's environment
MCP server: https://trendsfast.com/api/mcp/v3See agent setup, the API reference, Docs and the V3 OpenAPI.
V3: Global, Niche and Ask intelligence
Start with the shared saved index, explicit query credit ceilings and free saved-result reads. These implementation guides include labeled fixtures; current deployment and source availability remain separately verified.
- Use a trends API from Node.js — Query saved global observations, inspect evidence and rank a niche with explicit credit limits in a small server-side Node.js integration.
- Ask a trend question with Python — Build a small Python consumer that keeps an answer, exact source references, coverage and credits together without silently fetching new research.
- Connect an agent to TrendsFast through MCP — Understand the remote MCP endpoint, scoped OAuth or API keys, bounded query tools and free saved-result reads before connecting an agent.
- Measure trend growth from historical observations — Compare the same source entity and metric across retained timestamps, keep corrections visible and explain missing baselines without inventing a trend line.
- Define a niche without losing useful adjacent trends — Use confirmed audience, jobs, problems and exclusions to rank shared observations across CORE, ADJACENT and GLOBAL research rings.
- Audit trend evidence before your agent uses it — Separate source references, measured counters, permitted excerpts, media inspection and AI-search citations so an agent can explain what it knows.
- Budget trend API credits without duplicate queries — Use quotes, finite maximums, durable request IDs and free result recovery to control cached-query spending across REST and MCP.
All guides · Spin the public Trend Globe · V3 OpenAPI · MCP connection
Five products, one call
The dashboard’s five products are one request: POST /v3/trends/niche, or trendsfast_niche_trends over MCP, with your brand’s context_id and the product’s lens. Send the same input and your agent gets the view the dashboard shows. Naming the product collects your brand’s own sources fresh first, at that product’s price; a source read in the last few hours is reused, and an empty result costs nothing.
| Product | Question | Lens | What you get | Credits |
|---|---|---|---|---|
| Customers | What are my customers stuck on? | {"filters":{"content_types":["CONVERSATION"]}} | Find where your customers talk and what they’re stuck on, so you can answer them first and build what they ask for. | 10 |
| Trending | What’s trending in my niche, and next door? | no filter: every content type | Spot what’s gaining attention in your niche and the ones next to it, and turn it into content or features. | 25 |
| Competitors | What are my competitors doing? | no filter: read the COMPETITOR_ACTIVITY section of data.brief | See what your competitors post and which posts land, without checking every account yourself. | 30 |
| Formats | What videos work in my niche? | {"filters":{"content_types":["VIDEO"]}} | Learn which videos win attention in your niche, so your next one starts from evidence instead of a guess. | 20 |
| Search | What do people search for, and what do AI assistants answer? | {"filters":{"content_types":["SEARCH"]}} | Know what your customers search for, and whether ChatGPT, Claude, Gemini and Perplexity name you or your competitors when your buyers ask, so you write for the demand that exists. | 35 |
Authentication
Send the key as Authorization: Bearer $TRENDSFAST_API_KEY on REST and MCP. Create keys in API keys: each has the form tf_live_<prefix>.<secret>, the raw secret is shown once, and only a secure derived verifier and the prefix are stored.
A key belongs to one workspace and carries the scopes you choose: trends:query starts queries, trends:read reads results and brand context, and credits:read reads quotes, the balance and history. A read-only key leaves out trends:query. Keys expire 90 days after they are created and can be revoked on the same page at any time.
Claude, ChatGPT, Grok, Grok Bot, Claude Code, Cursor and VS Code connect with OAuth sign-in and consent for one project instead of a key, where OAuth is enabled. Over MCP, initialize and tools/list answer without a key so clients and directories can see the tools; every tool call needs a key or a sign-in, and a 401 names how to authenticate in its WWW-Authenticate header. Clients that sign in use https://trendsfast.com/api/mcp/v3/oauth, where every request needs one, so the first request starts sign-in. OAuth clients are pinned, so a client that needs dynamic client registration connects with a key. Signing in to the dashboard uses a private session rather than a reusable API key. Keep keys in your client’s environment or secret manager, never in a chat, a URL or a command argument.
Limits and credits
V3 queries spend credits from one balance shared by the dashboard, REST and MCP: at most 1 credit for Global, 3 credits for Niche, 5 credits for Ask, 5 credits for Discover over MCP and 5 credits for a video outlier check, and never more than the request’s own max_credits. Empty results, a video the outlier check does not find, saved reads, pagination and recovery cost 0 credits. A verified account receives 100 free credits once, then 50 every month; see pricing for plans and top-ups.
Which project, and whose credits. An API key works for the project it was created in, and a sign-in for the project chosen on the consent screen when it was approved; another project needs another key or a new connection. Credits belong to the account that owns the project: every project one account owns spends from the same balance, and a project of another account has its own. An agent can check both. accountId from trendsfast_credit_balance or GET /v3/trends/wallet names the balance; project_id and context.context_id from trendsfast_project_context or GET /v3/trends/context name the project and the brand. If MCP and REST return different ones, they are connected to different projects.
Queries are also admitted per account. On free credits, at most 2 can be in flight and 20 can start in any hour; once the account holds paid credits, 5 and 120. Each key has its own hourly request limit, a request body is at most 32 KB, and max_credits is at most 1,000. A 429 response carries Retry-After; wait, then retry with the same request ID.
Bounded errors
Every error body has an error code, and many add a recovery instruction. None of them is a reason to send the same query under a new request ID. Over REST, an INVALID_INPUT also lists fields, each with its path and problem, and a doc_url back to this page.
400The request body, a field or a cursor is invalid.
401The API key or connection is missing, invalid, expired or revoked.
402The quote is higher than max_credits, or the balance cannot cover the query.
403The key's scope, workspace or origin is not allowed.
404V3 is not enabled on this deployment, or the result or request was not found.
409The request ID was reused with different input, or is still in progress.
410The context or evidence is no longer eligible.
413The request body is larger than 32 KB.
415The request body was not sent as application/json.
429A concurrency or hourly limit was reached before the request was accepted, so nothing was charged. Wait, then send it again with the same request ID: seconds for concurrency, up to an hour for an hourly limit.
503The outcome is unconfirmed; read the request ID before deciding anything.
REST and MCP
Both call the same service, with the same scopes and the same credit balance. REST lives under https://trendsfast.com/v3/trends:
POST /v3/trends/global,/niche,/ask,/discoverand/outlierstart a query, with a body of{request_id, max_credits, input}. Each operation’s own fields go insideinput. TheX-Credits-Chargedheader says what the request cost. A product call collects its sources first, which can take about a minute.GET /v3/trends/results/{result_id}reads a saved result; add?cursor=for the next page. Add?view=compacthere, or to a query, for the much smaller view an MCP tool returns. Rereads are free until the result’sexpires_at, up to 30 days and sooner when a source’s terms end it; after it a read answers 410RESULT_EXPIREDwithexpired_atandnext_step.GET /v3/trends/requests/{request_id}returns the saved result for a request ID, or the state of that request.GET /v3/trends/quote?operation=global(orniche,ask,discoveroroutlier, and&product=for a product’s own price),/wallet,/history,/contextand/community-profilesread the price, the balance, settled results, brand context and your subreddits’ rules and culture as last read. A quote runs nothing and costs nothing.GET /v3/trends/communitieslists the communities TrendsFast has read in depth, and/communities/{name}returns one community’s brief.
Every GET above is free. The MCP server is https://trendsfast.com/api/mcp/v3, over Streamable HTTP with the key as a bearer token, and has 9 tools; the MCP page lists them. The REST contract is the OpenAPI 3.1 document at /v3/openapi.json.
The trendsfast CLI
For coding agents, the npm package trendsfast-cli installs the TrendsFast skill into each coding agent on the computer and signs in through the browser. The key stays in the CLI’s own credentials file and never enters a chat.
npx -y trendsfast-cli@latest initThen npx -y trendsfast-cli@latest doctor checks Node, the key, the connection, your brand and the installed skill, each with its fix. It is free and read-only.
LEGACY / V1
Legacy v1: for integrations built before V3
This section is for clients that already use a v1 project key with next_move:read and next_move:write. V1 and V3 keys are not interchangeable, and new integrations should start with the quickstart above.
Create once, then read
The project path identifies confirmed product context. The create request requires an active project-scoped bearer key and a caller-created UUID v4 idempotency key. It returns 202 while bounded work is queued or running, or 200 for an exact complete readback. Repeating the same key and input reuses the same request.
curl -X POST "https://trendsfast.com/v1/projects/<project_id>/today" \
-H "Authorization: Bearer $TRENDSFAST_API_KEY" \
-H "Idempotency-Key: <caller-generated-uuid-v4>" \
-H "Content-Type: application/json" \
-d '{
"objective": "Prepare one credible founder update",
"content_capabilities": ["founder_text"]
}'The four v1 endpoints
POST /v1/projects/{project_id}/todayGET /v1/projects/{project_id}/today/latestGET /v1/projects/{project_id}/trend-briefs/{brief_id}GET /v1/projects/{project_id}/trend-briefs/{brief_id}/creative-handoff
Lifecycle
A request moves through QUEUED and RUNNING, then completes as REVIEW_REQUIRED, READY, or explicit FAILED. A Marketing Play is always human-review-required; REST and MCP do not approve, deliver, publish, or schedule it.
Keys and allowance
Legacy v1 keys created in the dashboard expire within 24 hours. Legacy Agent access for v1 and the Marketing v2 MCP keeps its own allowance: three research starts per rolling 24 hours, shared across web, REST and MCP. Failed and erased runs count toward it, and a saved product profile is optional for topic research. Your agent creates content from the evidence; TrendsFast does not publish it.
Remote MCP v1 and the Marketing v2 MCP
Remote MCP v1 is served at https://trendsfast.com/api/mcp using stateless Streamable HTTP protocol 2026-07-28. It exposes exactly seven tools:
trendsfast_project_context_gettrendsfast_today_createtrendsfast_today_status_gettrendsfast_brief_latest_gettrendsfast_brief_gettrendsfast_creative_handoff_gettrendsfast_sources_get
Six tools are zero-effect reads. trendsfast_today_create is the one deliberate write and requires explicit intent, confirmed capabilities, and a caller-created UUID v4. The runtime OpenAPI 3.1 document is served at GET /v1/openapi.json. Public API access remains approval-gated until a project key has been issued.
The Marketing v2 MCP server at /api/mcp/v2 still answers existing Marketing v2 keys, with tools named trendsfast_marketing_*_v2. V3 keys carry no marketing scopes, so they list no tools there.
The v1 agent installer
The earlier installer adds a local stdio bridge to Remote MCP v1 for Generic stdio MCP, Claude Code and Codex, and stays for the installations already using it. New setups use the trendsfast CLI instead.
Keep your v1 key local
The pinned installer uses the project-scoped next_move:read and next_move:write workflow; these permissions do not grant billing, deletion or context editing. Subscription and allowance checks still apply. Run the installer in your own terminal and supply TRENDSFAST_API_KEY through your local secret manager or the hidden prompt in step 2 of the quickstart, which works the same for a v1 key. Never paste the value into an AI conversation, a command argument or shell history.
Start your chosen MCP client from that local environment, or use its documented secret configuration. Do not save a raw key in a repository or share the resulting configuration. This is local shell setup, not a credential collector in the installer.