API reference

Find endpoints for mentions, companies, and market context, with authentication and base credit costs beside each one.

Base URL
https://api.perception.to

Send a Perception key as Authorization: Bearer pcp_... where a route requires authentication.

Find an endpoint

20 of 20 endpoints

`GET /index`

Unmetered

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

Open without a key

`GET /indices`

Unmetered

Perception Index, Narrative Cost Basis, Narrative Consensus, Narrative Reach and Bitcoin Attention Share, the Bitcoin reading that supports Narrative Dominance (served at /indices/dominance).

Current headline readings are open. Add ?full=true with a Bearer token for methodology receipts, component breakdowns and bounded history (1 credit).

Open without a key

`GET /indices/dominance`

Unmetered

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

Open without a key

`GET /transparency-index`

Unmetered

Earnings-call directness scores per company, with the verbatim quotes behind each score.

Open, no key.

Open without a key

`GET /transparency-index/leaderboard`

1 base credit

Companies ranked by directness score.

Bearer token required

`GET /transparency-index/:ticker`

1 base credit

Full directness detail for one company, including scored quotes.

Bearer token required

`GET /feed`

1 base credit

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.

Bearer token required

`GET /trends`

2 base credits

AI-extracted narrative trends with signal strength and the mentions behind each cluster.

Bearer token required

`GET /intelligence`

3 base credits

Trend intelligence and category distribution.

Bearer token required

`GET /sentiment-metrics`

1 base credit

Historical sentiment series, by day and by outlet.

Bearer token required

`GET /fear-greed-index`

1 base credit

Bitcoin Fear & Greed Index history.

Bearer token required

`GET /channel-volume`

1 base credit

Mention volume broken down by outlet and channel.

Bearer token required

`POST /grouped-data`

2 base credits

Entity recognition over a body of text: company mentions with counts and sentiment.

Bearer token required

`GET /cohorts`

1 base credit

Sentiment split by the role of the speaker: execs, devs, analysts, investors, media and more.

Bearer token required

`GET /evadometer`

1 base credit

Evade-o-Meter directness scoring across tracked companies.

Bearer token required

`GET /evadometer/leaderboard`

1 base credit

Companies ranked by how directly management answers.

Bearer token required

`GET /evadometer/:ticker`

1 base credit

Evade-o-Meter detail for one company.

Bearer token required

`GET /v1/spaces/:id/rows`

1 base credit

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.

Bearer token required

`GET /v1/brains/:id`

2 base credits

A Brain you own: the collected post history behind it.

Bearer token required

`POST /workflow-runs`

1 base credit

Metadata-only execution receipts for configured agent workflows.

Stores run status and timing without storing the workflow prompt or generated output.

Bearer token required

Read credit rules and the complete reference