Every endpoint, every tool, and what each one costs
33 registered MCP tools and 20 REST endpoints. Find the inputs, returned data, authentication, and credit costs.
Credits
What a call costs
Every billable MCP and REST request uses the same calculation: the tool's base weight, plus 1 credit for each requested 25-result block, capped at 10 credits. The table shows each tool's base component. Taxonomy and usage checks are unmetered.
Free
5credits/day
31 metered research tools
No card required. Taxonomy and usage checks are unmetered.
Perception
1,000credits/month
31 metered research tools
Shared across REST, MCP, users, and named agent credentials.
Intelligence
8,000credits/month
31 metered research tools
Shared across REST, MCP, users, and named agent credentials.
- Cost is the tool base weight plus 1 credit for each requested 25-result block, capped at 10 credits per call.
- Included credits are used first, followed by grandfathered prepaid balance and explicitly enabled subscriber overage.
- Registered metered usage costs $0.05 per weighted credit and is limited to 20 paid credits per day.
- Subscriber overage costs $0.025 per weighted credit. Saved-card overage stays off until the account owner enables it.
- x402 accountless access costs $0.10 per weighted credit.
- 60 requests per minute across both surfaces.
- Full-text article calls draw on a separate 200/day pool as well as credits.
REST
Every REST endpoint
Base URL https://api.perception.to. Every route also answers under a /v1 prefix. REST calls use the same weighted calculation and shared account pool as MCP.
| Endpoint | What it fetches | Credits |
|---|---|---|
/indexGETNo key | Perception Index score, status, 24h/7d change, confidence and decomposed drivers. Updated every 15 minutes.Open, no key. Add ?full=true with a Bearer token for divergences and returns by sentiment regime (1 credit). | Free |
/indicesGETNo key | Perception's five-index family: Perception Index, Bitcoin Discourse Dominance, Narrative Cost Basis, Cohort Conviction Gap and Perception Breadth.Current headline readings are open. Add ?full=true with a Bearer token for methodology receipts, component breakdowns and bounded history (1 credit). | Free |
/indices/dominanceGETNo key | Multi-asset Narrative Dominance rankings across the tracked universe.The current ranking is open. Add ?full=true or ?include_history=true with a Bearer token for protected detail and history (1 credit). | Free |
/transparency-indexGETNo key | Earnings-call directness scores per company, with the verbatim quotes behind each score.Open, no key. | Free |
/transparency-index/leaderboardGETBearer | Companies ranked by directness score. | 1 |
/transparency-index/:tickerGETBearer | Full directness detail for one company, including scored quotes. | 1 |
/feedGETBearer | Mention search across thousands of sources with full-text search, date, outlet and sentiment filters.Also accepts x402 pay-per-call in USDC without a subscription, which is why an unkeyed request returns 402 rather than 401. | 1 |
/trendsGETBearer | AI-extracted narrative trends with signal strength and the mentions behind each cluster. | 2 |
/intelligenceGETBearer | Trend intelligence and category distribution. | 3 |
/sentiment-metricsGETBearer | Historical sentiment series, by day and by outlet. | 1 |
/fear-greed-indexGETBearer | Bitcoin Fear & Greed Index history. | 1 |
/channel-volumeGETBearer | Mention volume broken down by outlet and channel. | 1 |
/grouped-dataPOSTBearer | Entity recognition over a body of coverage: company mentions with counts and sentiment. | 2 |
/cohortsGETBearer | Sentiment split by the role of the speaker: execs, devs, analysts, investors, media and more. | 1 |
/evadometerGETBearer | Evade-o-Meter directness scoring across tracked companies. | 1 |
/evadometer/leaderboardGETBearer | Companies ranked by how directly management answers. | 1 |
/evadometer/:tickerGETBearer | Evade-o-Meter detail for one company. | 1 |
Account-scoped routes3 endpoints
| Endpoint | What it fetches | Credits |
|---|---|---|
/v1/spaces/:id/rowsGETBearer | Rows from a Space you own, in the same shape as its CSV export. Cursor-paginated, 50 per page by default.Returns 404 rather than 403 on a Space you do not own, so the API never confirms that someone else’s Space exists. | 1 |
/v1/brains/:idGETBearer | A Brain you own: the collected post history behind it. | 2 |
/workflow-runsPOSTBearer | Metadata-only execution receipts for configured agent workflows.Stores run status and timing without storing the workflow prompt or generated output. | 1 |
MCP
All 33 MCP tools
Connect Claude, ChatGPT or Cursor and these become callable directly. Every tier can use all 33 tools. Each accepted research request uses its published weighted cost. Taxonomy and usage checks are unmetered. The Base credits column shows the tool component; requested result volume can increase the total to a maximum of 10 credits.
Research16 tools
| Tool | What it fetches | Base credits |
|---|---|---|
perception_get_market | Bitcoin price, market cap, chain reference metrics and the Perception Index.“Price, block height and the Index, for a report dateline.” | 1 |
perception_guide | In-agent onboarding and workflow templates.“What can Perception do, and how should I use it?” | 1 |
perception_get_subject_taxonomy | Canonical subject labels and accepted aliases for precise query construction.“Which subject labels should I use for a custody research query?” | Free |
perception_get_usage | Current weighted-credit usage, funding state, reset time, overage status, and credential totals.“How many credits are left before this workflow continues?” | Free |
perception_daily_radar | Daily briefing: anomalies, sentiment shifts, emerging narratives, and material company announcements.“What changed overnight?” | 2 |
perception_get_index | The five-index Perception portfolio with current readings, confidence, components and optional history.“Show me every Perception proprietary index and what each says now.” | 1 |
perception_search_mentions | Search thousands of sources for coverage, fundraising announcements, capital raises, partnerships, and other company signals.“Which digital asset companies announced funding rounds this month?” | 1 |
perception_get_trends | AI-extracted narrative trends with signal strength.“Which narratives are gaining signal strength right now?” | 2 |
perception_get_sentiment | Historical sentiment by day and by outlet.“How has sentiment toward stablecoins moved this quarter?” | 1 |
perception_get_categories | Trend category distribution.“Which categories dominate coverage this month?” | 1 |
perception_search_companies | Entity-recognition company search, more accurate than keyword matching.“Which companies keep coming up alongside custody?” | 2 |
perception_compare_entities | Two to five companies side by side: volume, sentiment, sources.“Compare Coinbase, Kraken and Gemini on volume and sentiment.” | 2 |
perception_narrative_momentum | Whether a topic is accelerating, steady or fading.“Is tokenization accelerating or fading?” | 1 |
perception_top_mentions | Top entities or topics by mention count for a date range or outlet.“Who was mentioned most at DAS NYC?” | 1 |
perception_cohort_sentiment | Sentiment split by speaker role: execs, devs, analysts, media.“Are developers more bearish than executives here?” | 1 |
perception_get_evadometer | Earnings-call directness scores.“Which management teams dodge the most questions?” | 1 |
Entity intelligence2 tools
| Tool | What it fetches | Base credits |
|---|---|---|
perception_get_entity_profile | Full entity picture: coverage, analyst view, trends, relationships, timeline.“Give me everything on Circle.” | 3 |
perception_media_radar | Outlet-specific coverage analysis.“How does Bloomberg cover this differently from CoinDesk?” | 1 |
Extended research15 tools
| Tool | What it fetches | Base credits |
|---|---|---|
perception_get_analyst_ratings | Analyst consensus, price targets and rating changes for covered tickers.“What is the analyst consensus on MSTR?” | 1 |
perception_search_regulatory | Regulatory filings, enforcement actions and policy documents by agency and jurisdiction.“What has the SEC published on custody this year?” | 1 |
perception_get_article | Full text of a single article.“Pull the full text of this piece.” | 3 |
perception_save_research | Save a research note with findings and topics (90-day retention).“Save this finding so I can come back to it.” | 1 |
perception_recall_research | Retrieve saved research notes by recency or topic.“What did I find on this last month?” | 1 |
perception_scenario_analysis | Test a hypothetical against historical analogues: sentiment arcs, narrative half-life.“If an ETF were rejected, how has coverage behaved before?” | 3 |
perception_get_insider_activity | SEC Form 4 insider trades with cluster alerts.“Are insiders at this company buying or selling?” | 1 |
perception_get_earnings_intelligence | Earnings-call analysis: management tone, directness, notable quotes.“How direct was management on the last call?” | 1 |
perception_get_intelligence_digest | Cross-signal briefing fusing analyst actions, sentiment, earnings and regulatory moves.“One briefing across every signal today.” | 3 |
perception_search_voices | Search earnings transcripts, conferences, and podcasts for keywords, with snippets and timestamped occurrences.“What have speakers said about stablecoins in podcasts and earnings calls?” | 1 |
perception_get_brains_corpus | Bulk corpus access for a tracked voice or entity.“Everything this executive has posted.” | 2 |
perception_get_divergences | Where narrative and capital disagree.“Where does the narrative disagree with the money?” | 1 |
perception_get_capital_exposure | 13F holdings, treasury positions and beneficial ownership for an entity.“Who holds this stock, and how has that changed?” | 1 |
perception_get_hiring | Open roles and hiring posture for a company from its public ATS board.“Is Kraken hiring right now, and for what?” | 1 |
perception_hiring_leaderboard | Companies ranked by open roles across the tracked universe, by sector and function.“Which crypto companies are hiring the most right now?” | 1 |
Schema
What a mention looks like
Every mention returned by /v1/feed and the search tools has this shape, whether it started as an article, a post, a podcast transcript or a filing.
| Field | Type | Description |
|---|---|---|
Title | string | Article headline, or @handle for tweets |
Content | string | Full article text or tweet body |
Date | string (ISO 8601) | Publication timestamp, UTC |
URL | string | Source URL |
Outlet | string | Source name (e.g. Bloomberg, X, CoinDesk) |
Sentiment | string | Positive, Neutral, or Negative |
Outlet_Category | string | Crypto Media, Financial Media, Social Media, Regulatory, Podcast, GitHub |
author_name | string | null | Author name (media articles only) |
image_url | string | null | Article thumbnail or OG image |
Agent discovery
Agents can find the API, the MCP server and these docs without a human in the loop. If you are not writing an agent, you can skip this.
| perception.to/llms.txt | Plain-language site guide for language models |
| perception.to/.well-known/mcp.json | MCP server descriptor: tools, auth, transport |
| perception.to/.well-known/agent.json | Agent card with capabilities and endpoints |
| perception.to/.well-known/api-catalog | RFC 9727 API catalog |
| perception.to/.well-known/oauth-authorization-server | OAuth 2.1 discovery for MCP clients |
| perception.to/.well-known/agent-skills/index.json | Installable agent skills |
robots.txt Content-Signal: search=yes, ai-input=yes, ai-train=no. Live agents welcome; training on the archive is not.
Get a key and start calling
Start free, enable registered metered access, or choose a plan with a monthly shared pool.