Common questions
How Earshot works, what you can query, and what candidate plans include. Something missing? Write us at hello@earshot.gg.
Product
What is Earshot?
Earshot lets you select an eligible Public Discord Server Archive and query its observable history and live updates through REST, full-text search, or hosted MCP. Earshot does not post to Discord.
How far back does history go?
Earshot imports the messages Discord still exposes in selected channels. It cannot recover content deleted before observation or hidden by permissions. Coverage reports known limits.
How fresh is the data?
Earshot has not published a freshness SLA. It records live updates after the bot connects. If the bot connection is interrupted, committed archive data remains queryable. Coverage reports the last confirmed live continuity and known gaps.
What can I query?
You can list messages by channel or creation time and page with opaque continuation cursors. You can also fetch one message by ID and search current archived message content. A separate endpoint lists channels visible to your credential, and Coverage reports what Earshot could observe.
How do agents use it?
Add https://api.earshot.gg/mcp to a Streamable HTTP MCP client and authenticate with an esk_... API credential. Earshot provides three read-only tools: search_messages, get_messages, and list_channels.
What does a successful API response include?
Every successful v1 REST response returns four top-level fields: data, page, coverage, and as_of. The coverage field summarizes the archive data visible to the credential. The as_of field identifies the archive incarnation and revision used for the read.
Access and data
What do server members see?
The Earshot bot appears in the server's member list. It reads only channels allowed by Discord permissions and Earshot's selected scope. It does not post.
Which channels get read?
Earshot selects one shared set of channels for each Server, and Discord permissions can narrow it further. Customers can limit which channels their users and services query, but cannot expand what Earshot observes.
How is access controlled?
Your account selects an eligible Public Server Archive within its plan allowance. Access grants limit each user or service to the whole server or selected channels. API credentials limit actions and are stored only as hashes.
What does a message include?
Each message includes decimal-string message and channel IDs, content, and Discord timestamps for creation and the latest observed edit.
What happens if I cancel?
Under the candidate cancellation policy, paid archive access, grants, and API credentials become inactive. The shared archive is not deleted. Retention and erasure timelines are still unsettled.
Candidate plans
How is usage metered?
One REST request counts as one API request. One MCP tool call counts the same; MCP setup and tool discovery are not metered. Candidate plans add a monthly request cap and a per-credential rate limit.
What happens when I hit my cap?
The candidate policy sends notices at 80% and 100% of the monthly cap. It continues serving requests through 120%, then returns 429 until the cap resets or you upgrade. This is not yet a launched plan.
Can I change plans?
Under the candidate plan design, you choose which Public Server Archives you keep access to after a downgrade. Access to the rest stops authorizing future reads without deleting the shared archives.
Is anything free?
The planned demo server uses a shared read-only credential and requires no account. Other Public Server Archives require a paid plan.
Still deciding?
Preview the planned API requests and responses before joining early access.
Preview API examples