Reference
Every endpoint, every tool, and what each one costs
31 MCP tools and 17 REST endpoints. What each one returns, what you would ask it for, and the credits it spends.
31
MCP tools
17
REST endpoints
2
Open without a key
Credits
What a call costs
Allowances are counted in credits, and most calls cost 1. The heavier tools cost more, and asking for a lot more results at once costs more, so a cheap question stays cheap. Every tool’s cost is listed in the tables below. On Intelligence and Team, every call is 1 credit whatever its size.
Free
5/day
14 tools
Weighted pricing. Enough to try the tools, not to run on.
Standard
20/day
16 tools
Adds entity profiles and media radar.
Intelligence
100/day
31 tools · flat rate
Every tool, and every call costs exactly 1 credit at any size.
- REST and MCP have separate daily pools. Spending one does not touch the other.
- 60 requests per minute across both surfaces.
- Full-text article calls draw on a separate 200/day pool as well as credits.
- Team plans run monthly pools instead of daily: 15,000 requests and 1,000 full-text, with metered overage.
REST
Every REST endpoint
Base URL https://api.perception.to. Every route also answers under a /v1 prefix. REST calls are a flat 1 credit and draw on their own pool.
| 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 |
/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 1,000+ 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. | 1 |
/intelligenceGETBearer | Trend intelligence and category distribution. | 1 |
/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. | 1 |
/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 routes2 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. | 1 |
MCP
All 31 MCP tools
Connect Claude, ChatGPT or Cursor and these become callable directly. The 9 tools priced above 1 credit are the ones that fan out across several queries or return full text.
Free · every plan14 tools
| Tool | What it fetches | Credits |
|---|---|---|
perception_search_mentions | Search 1,000+ sources with sentiment, outlet, language and region filters.“Every mention of Coinbase last week, negative only.” | 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_market | Bitcoin price, market cap, chain reference metrics and the Perception Index.“Price, block height and the Index, for a report dateline.” | 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_guide | In-agent onboarding and workflow templates.“What can Perception do, and how should I use it?” | 1 |
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_daily_radar | Daily briefing: anomalies, sentiment shifts, emerging narratives.“What changed overnight?” | 2 |
perception_get_index | The Perception Index with drivers and velocity.“What is the Index today, and what is driving it?” | 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 |
Standard and above2 tools
| Tool | What it fetches | 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 |
Intelligence and Team15 tools
| Tool | What it fetches | 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 reporters and commentators by beat, outlet and coverage pattern.“Which reporters cover mining regulation?” | 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
One key works across both the REST API and the MCP server.
Start 14-day trial