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.

  1. 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.

  2. 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:query and credits: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:

    Load the key into your terminal
    printf "TrendsFast API key: "; read -rs TRENDSFAST_API_KEY; echo; export TRENDSFAST_API_KEY
  3. Make your first query. Global is the cheapest query: it costs at most 1 credit and needs no brand context. Every query carries a request_id you generate and keep, and a max_credits ceiling 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.

    First query: Global
    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 }
    }
    EOF

    The first line makes the request ID with uuidgen, or with Python where uuidgen is missing. Keep the terminal open: the next step reads the same $REQUEST_ID.

  4. Read it again for free. The same request ID returns the saved result, with usage.this_request_credits at 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.

    Reread the saved result
    curl -sS https://trendsfast.com/v3/trends/requests/$REQUEST_ID \
      -H "Authorization: Bearer $TRENDSFAST_API_KEY"

    Later, read it by the result_id in the response at GET /v3/trends/results/{result_id}, and pass ?cursor= with its next_cursor for the next page. Reads, pagination and recovery cost 0 credits.

  5. 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.

    Any MCP client
    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.

  1. 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.
  2. Create a key in API keys. It is shown once and is scoped to one workspace with trends:query, trends:read and credits:read. Keep it in TRENDSFAST_API_KEY in your client’s environment, never in chat, URLs or command arguments.
  3. Add the remote MCP server https://trendsfast.com/api/mcp/v3 with that key as a bearer token, or call REST under /v3/trends. Both share one service, one set of scopes and one credit balance.
  4. Ask one bounded question. Every query carries a request_id UUID you keep and a max_credits ceiling. A Global query costs at most 1 credit, Niche 3 credits, Ask 5 credits. Empty results cost nothing.
  5. 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 its request_id cost 0 credits and never start new research. After it, a read answers RESULT_EXPIRED; the query runs again under a new request_id, at its price.
The authenticated MCP tools
ToolCostWhat it does
trendsfast_discover_trends5 creditsOne question across global, core and adjacent scope and every channel.
trendsfast_global_trends1 creditWhat is trending across the shared index. No brand context needed.
trendsfast_niche_trends35 creditsTrends ranked against your niche. Name a product to collect your brand's sources fresh first.
trendsfast_ask_trends5 creditsOne bounded question, answered from saved evidence.
trendsfast_video_outlier5 creditsOne TikTok, Instagram or YouTube video against its creator's recent posts. Charged only when found.
trendsfast_read_resultfreeReread or page through a saved result, or recover a lost response.
trendsfast_community_brieffreeRead before drafting for a subreddit, free: its people, how to sound, the winning post and reply, its rules.
trendsfast_project_contextfreeThe connected brand and its confirmed niche context.
trendsfast_credit_balancefreeThe 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_id and 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/mcp and the Marketing v2 MCP at /api/mcp/v2 are 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.
V3 MCP connection
TRENDSFAST_API_KEY=<your key>   # set in the client's environment
MCP server: https://trendsfast.com/api/mcp/v3

See 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.

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.

FIVE PRODUCTS · ONE NICHE CALL
ProductQuestionLensWhat you getCredits
CustomersWhat 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
TrendingWhat’s trending in my niche, and next door?no filter: every content typeSpot what’s gaining attention in your niche and the ones next to it, and turn it into content or features.25
CompetitorsWhat are my competitors doing?no filter: read the COMPETITOR_ACTIVITY section of data.briefSee what your competitors post and which posts land, without checking every account yourself.30
FormatsWhat 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
SearchWhat 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.

400

The request body, a field or a cursor is invalid.

401

The API key or connection is missing, invalid, expired or revoked.

402

The quote is higher than max_credits, or the balance cannot cover the query.

403

The key's scope, workspace or origin is not allowed.

404

V3 is not enabled on this deployment, or the result or request was not found.

409

The request ID was reused with different input, or is still in progress.

410

The context or evidence is no longer eligible.

413

The request body is larger than 32 KB.

415

The request body was not sent as application/json.

429

A 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.

503

The 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, /discover and /outlier start a query, with a body of {request_id, max_credits, input}. Each operation’s own fields go inside input. The X-Credits-Charged header 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=compact here, or to a query, for the much smaller view an MCP tool returns. Rereads are free until the result’s expires_at, up to 30 days and sooner when a source’s terms end it; after it a read answers 410 RESULT_EXPIRED with expired_at and next_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 (or niche, ask, discover or outlier, and &product= for a product’s own price), /wallet, /history, /context and /community-profiles read 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/communities lists 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.

TrendsFast CLI install command
npx -y trendsfast-cli@latest init

Then 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.

The CLI with every other way to connect

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.

Create a v1 Customer Demand Brief
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}/today
  • GET /v1/projects/{project_id}/today/latest
  • GET /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_get
  • trendsfast_today_create
  • trendsfast_today_status_get
  • trendsfast_brief_latest_get
  • trendsfast_brief_get
  • trendsfast_creative_handoff_get
  • trendsfast_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.