The reference below describes what the API will return at launch. Everything documented here works against the same OpenAPI spec, available at /openapi.json.
Spec version: 0.3.0. Status: status page coming soon.
How to get your API key
Your key is created and shown in your account dashboard under API keys. Code samples below use YOUR_API_KEYas a placeholder — swap in your real key (it's prefixed sa_live_) to run them.
Getting started
From signup to first successful response in under five minutes:
Get a key.Sign up on the pricing page — Free tier, no card required. Your API key appears in the dashboard immediately after email verification. Keys start with sa_live_ and are shown once; store it in an env var, not in code.
Find a call ID. Call IDs follow the format call_{TICKER}_{YYYY}Q{Q}_earnings. The most recent AAPL call ID is visible from GET /companies/AAPL/earnings-calls (Free tier, live today).
Fetch the analysis:
Replace YOUR_API_KEY in the samples below with your actual key from your account dashboard.
{
"call_id": "call_AAPL_2026Q2_earnings",
"narrative": "Management language showed increased hedging around
the guidance discussion. CFO prepared remarks were more qualified
than the prior two calls.",
"risk_index": 6.8, // 0–10 composite language-risk score
"risk_bin": "medium", // "low" | "medium" | "high"
"cohort_percentile": 0.72,// rank vs. historical sector cohort
"relevant_guidance": "We expect revenue in the range of $X to $Y,
subject to macroeconomic conditions.",
"calibrated_p_miss_90d": 0.61, // model output — not a guarantee
"methodology_version": "v1.0",
"wall_safe": true // false on Free tier (narrative only)
}
Authentication & rate limits
Every request requires Authorization: Bearer <key>. No session cookies, OAuth, or basic auth. Keys are scoped to one account and one tier — treat them like passwords.
Token format
Authorization: Bearer YOUR_API_KEY
Where to find your key
Keys are generated in the API dashboard under Account → API keys. Each key is shown once at creation — copy it immediately and store it as an environment variable (SPOKEN_ALPHA_API_KEY is the conventional name). Never commit keys to source control or include them in client-side code.
Per-tier rate limits
Tier
Calls / month
Calls / hour
Free
1,000
60
Starter
5,000
600
Pro
50,000
3,000
Enterprise
Custom
Custom
x402 pay-per-call ($0.02/call) is not subject to monthly quotas. Tier 2 overage on Pro is billed at $0.05/call beyond the monthly quota — set a hard cap in the dashboard to prevent this.
Retry-After and response headers
A 429 from an hourly limit includes . Read it and wait before retrying — back-off loops that ignore it will keep hitting 429.
Endpoint reference
Auto-generated from the OpenAPI spec. Endpoints are grouped by tier; access depends on your plan.
Error reference
Non-2xx responses return JSON. 500-level errors include a request_id — quote it when contacting support. Every error response also carries a documentation_url that deep-links into the full error code reference.
401unauthorizedMissing or invalid Authorization header.
Example response body
{"detail": "Authentication credentials were not provided."}
What to do
Check that your request includes Authorization: Bearer <key>. Keys start with sa_live_.
403forbiddenValid key but tier doesn't include this endpoint or field.
Example response body
{"detail": "Tier 'free' does not include access to this field. Upgrade to access."}
What to do
Upgrade your plan at /pricing. Check which tier is required in the endpoint reference.
404
Changelog
Material changes to the API and SDK ship here. Breaking changes get a new major version (/v2) and never land in /v1.
v0.3.02026-06-10
New:GET /language-patterns/search — full-text language pattern search across the transcript corpus with per-result outcome data and aggregate return statistics. Available on all tiers.
New: Tier 2 — analysis endpoints documented (/calls/{call_id}/analysis, /calls/{call_id}/summary, POST /text/score) — currently scaffolded; data ships with private-beta key rollout.
v0.2.02026-05-30
Initial public spec. Tier 1 metadata endpoints live: GET /companies/{ticker}/ir-page and GET /companies/{ticker}/earnings-calls.
Want a heads-up at launch?
Review the tiers, then drop your email so we can let you know when keys are issued.
Returns the canonical Investor Relations page URL. Paid tiers also get validation metadata (last-validated timestamp, validation status, planned confidence score, and detected sections). Free tier returns URL only plus a tier_notice pointer to /pricing.
Parameters
Name
In
Type
Required
Description
ticker
path
string
yes
Uppercase US ticker (case-insensitive normalized at the boundary).
200IR page metadata. Free tier returns the slim shape; paid tiers return the full shape.
401Missing or invalid API key.
404ticker_not_found (no company on file) or ir_page_not_found (company exists but no IR URL on file).
429Rate limit or quota exceeded.
IRPageResponse
Field
Type
Required
Description
ticker
string
yes
—
company_name
string
yes
—
ir_page
object
yes
—
tier_notice
string
no
Free tier only — pointer to /pricing for the upgrade unlock.
get/companies/{ticker}/earnings-callsLive
Recent earnings calls for a company
Returns recent earnings calls in reverse chronological order. Each call includes fiscal period, scheduled date, BMO/AMC flag, and confirmed status. Asset URLs (audio / slide deck) are part of the v1 contract but currently null pending the IR-page section crawler launch. transcript.parsed_url is always null — transcript-fetching endpoints were removed 2026-06-19.
Press releases for a company (scaffolded; not yet available)
Structured recent IR-page press releases for the company. The endpoint is scaffolded so clients can integrate against the locked contract today, but returns 503 data_not_yet_available until the SEC 8-K Item 2.02 + EX-99.1 ingest ships. Planned launch: Q3 2026.
Returns a language-pattern analysis for the earnings call: a risk index, risk bin, cohort percentile, plain-English narrative, and a calibrated probability metric. The wall_safe field indicates whether the full analysis or a narrative-only summary is returned — full analysis requires Starter tier or above. Does NOT expose raw per-speaker deviation scores, baseline counts, or proprietary composition weights.
200Call analysis. Full shape on Starter+; narrative-only on Free.
401Missing or invalid API key.
404call_not_found.
429Rate limit or quota exceeded.
503data_not_yet_available — analysis has not yet run for this call.
CallAnalysis
Field
Type
Required
Description
call_id
string
yes
—
risk_index
number (float)
no
Composite language-risk score for the call. Null on Free tier (narrative-only response).
risk_bin
get/calls/{call_id}/summaryScaffolded
Executive summary for a call
Returns a concise plain-English summary of the earnings call: key themes, notable speaker statements, and guidance highlights. Generated from the parsed transcript. Available on Starter tier and above.
Accepts a block of text and an optional speaker identity, and returns a deviation rating relative to that speaker's historical baseline. Intended for pre-flight scoring of non-transcript surfaces (press releases, interviews, written statements). Does NOT expose raw per-speaker z-scores or baseline counts. Speaker identity must correspond to a tracked executive in the Spoken Alpha corpus.
Example request
curl -X POST "https://api.spokenalpha.com/v1/text/score" \
-H "Authorization: Bearer $SPOKEN_ALPHA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"We are pleased to report strong results this quarter, though we remain cautious about the near-term outlook given ongoing market conditions.","speaker_identity":"Tim Cook","ticker":"AAPL"}'
Responses
200
Tier 3 — language patterns
get/language-patterns/searchLive
Search earnings call language patterns
Full-text search across all ingested earnings call transcripts. Returns matching statement snippets with call context, per-result realized return outcomes (day-of, 5d, 30d, next-call), and aggregate return statistics across the result set. Results are phrase-level matches from prepared remarks and Q&A exchanges.
Phase 1 returns exact full-text matches only; semantic (pgvector) close-match search ships in Phase 2. `sort=signal_score` requires Pro tier or above and is planned for Phase 4.
Parameters
Name
In
Type
Required
Description
q
query
string
yes
Search query. Phrase or boolean full-text (AND / OR / NOT / parentheses). Case-insensitive.
companies
query
string
no
Filter by ticker. Repeatable: ?companies=AAPL&companies=MSFT.
executives
query
string
no
Filter by speaker name. Repeatable.
statement_kind
query
string
no
Restrict to prepared remarks, analyst questions, or management answers.
sector
query
string
no
Filter by GICS sector (partial match).
date_from
query
date
no
Inclusive start date (YYYY-MM-DD).
date_to
query
date
no
Inclusive end date (YYYY-MM-DD).
sort
query
string
no
Result ordering. `signal_score` requires Pro tier or above (Phase 4).
offset
query
integer
no
Result offset for relevance sort. Hard-capped at 500.
cursor
query
string
no
Opaque pagination cursor (recency sort only — returned in prior response).
Fix the field listed in loc. Check the endpoint's parameter table for required fields and types.
429rate_limitPer-hour rate limit or monthly quota exceeded.
Example response body
{"detail": "Request was throttled. Expected available in 42 seconds."}
What to do
Read the Retry-After response header (seconds) and wait that long before retrying. For monthly quota exhaustion, upgrade or wait for the calendar month to reset at 00:00 UTC.
500server_errorUnexpected internal error.
Example response body
{"detail": "Internal server error.", "request_id": "7f3a2b4d-..."}
What to do
Quote the request_id when contacting hello@spokenalpha.com. Safe to retry once after a brief pause.
503unavailableEndpoint is scaffolded but data hasn't shipped yet, or upstream pipeline is temporarily down.
200Paginated list of earnings calls, newest first.
401Missing or invalid API key.
404No company found for ticker.
422Invalid query parameter (limit out of range, malformed date, etc.).
429Rate limit or quota exceeded.
EarningsCallListResponse
Field
Type
Required
Description
ticker
string
yes
—
calls
array<EarningsCall>
yes
—
pagination
Pagination
yes
—
200Paginated list of press releases (planned shape; not returned in v1).
401Missing or invalid API key.
503data_not_yet_available — the data backing this endpoint has not yet shipped. Body includes planned_launch.
PressReleaseListResponse
Field
Type
Required
Description
ticker
string
yes
—
press_releases
array<PressRelease>
yes
—
pagination
Pagination
yes
—
string
no
Discretized risk category. Null on Free tier.
cohort_percentile
number (float)
no
Percentile rank against historical calls in the same sector cohort. Null on Free tier.
narrative
string
no
Plain-English summary of the language patterns observed in this call. Returned on all tiers.
relevant_guidance
string
no
Key guidance statements that influenced the analysis. Null on Free tier.
calibrated_p_miss_90d
number (float)
no
Model-calibrated probability of an earnings miss in the 90-day window following this call. Null on Free tier. This is a model output, not a guarantee — see methodology_version for the model version used.
methodology_version
string
yes
Version identifier for the analysis methodology. Pin this when building reproducible pipelines.
wall_safe
boolean
yes
True if this response contains the full analysis (Starter tier+). False if only the narrative is present (Free tier).
200
Call summary.
401Missing or invalid API key.
404call_not_found.
429Rate limit or quota exceeded.
503data_not_yet_available — summary has not yet been generated for this call.
CallSummary
Field
Type
Required
Description
call_id
string
yes
—
summary
string
yes
Concise plain-English summary of the earnings call.
key_themes
array<string>
no
Top themes extracted from the call.
speakers
array<object>
no
—
methodology_version
string
yes
—
Text score result.
401Missing or invalid API key.
404speaker_not_found — no tracked speaker matches the provided identity.
422Invalid request body (missing text, text too short, etc.).
429Rate limit or quota exceeded.
TextScoreResponse
Field
Type
Required
Description
rating
number (float)
yes
Language deviation rating relative to the speaker's historical baseline (or cross-cohort if no speaker provided). Higher values indicate greater deviation from the speaker's established patterns.
rating_bin
string
no
—
narrative
string
no
Plain-English explanation of the rating.
speaker_matched
boolean
no
True if speaker_identity was resolved to a tracked executive. False if scoring used cross-cohort baseline.
methodology_version
string
yes
—
wall_safe
boolean
yes
—
aggregate
array<LanguagePatternAggregate>
yes
Return statistics aggregated over all matching results. One entry per return window. Suppressed (empty array) when total_count < 30.
warnings
array<LanguagePatternWarning>
no
Data-quality and composition warnings (sector concentration, temporal skew, thin sample).
next_cursor
string
no
Pagination cursor for the next page (recency sort). Null when no further results.