A simple REST API.
One consistent schema.
Everything you need to query the Konseki API — authentication, parameters, rate limits, error handling, and the full response schema. No SDK required; this is a plain REST API that works with any HTTP client.
Authentication
Every request requires an API key, passed as a header. API access is included on plans that offer it — see the Pricing page. Your key is in your dashboard once your plan includes API access.
Requests without a valid key return 401 Unauthorized. Treat your key like a password — don't share it, commit it to public repositories, or expose it in client-side code. If your key is compromised, log in to your dashboard to view your account, or email hello@konseki.io for help.
Rate limits
Limits are applied per API key. Current limits for each plan are published on the Pricing page. Each call to /analysis/{symbol}-{exchange} counts as one request, regardless of how many forward windows or fields you read from the response — every forward window comes back in a single call. Plans described as unlimited are intended for ordinary use and remain subject to fair-use protection against automated abuse; requests that trip a limit return a 429.
"error": "rate_limit_exceeded",
"message": "Request limit reached. Contact support if you need a higher limit.",
"request_id": "a165f32238788df6",
"plan": "pro"
}
Get historical context for a symbol
Returns pre-computed historical context for a single symbol at a given lookback period. The response includes all 4 forward windows nested inside — no need to make a separate request per forward window.
{symbol}-{exchange} is a single combined path segment, hyphen-separated — e.g. AAPL-NASDAQ, A-NYSE. This disambiguates symbols that exist on multiple exchanges and matches the same slug format used throughout Explore page URLs.
Not sure which symbol/exchange combination to use? Fetch /v1/symbols for a given country to browse every valid combination programmatically, or browse them on the Explore page in your dashboard — each row links to a symbol page whose URL is exactly the path segment this endpoint expects.
Parameters
| Parameter | Values | Description | |
|---|---|---|---|
| country | required | US, CN | Country the symbol trades in. See /v1/countries for supported codes. |
| lookback | required | 5, 10, 15, 20, 25, 30, 40, 50 | Lookback window in trading days. Each value returns a separate set of matches and forward outcomes. |
| date | optional | YYYY-MM-DD | Retrieve a specific historical snapshot instead of the latest. Resolves directly to that date's stored output — no recomputation. If omitted, resolves to the most recent available date. |
Example request
"https://api.konseki.io/v1/analysis/AAPL-NASDAQ?country=US&lookback=15"
Example response (trimmed)
"meta": {
"data_through": "2026-06-17",
"timeframe": "1d",
"country": "United States",
"lookback_periods": 15
},
"benchmark": {
"symbol": "AAPL",
"exchange": "NASDAQ",
"name": "Apple Inc.",
"context": { /* all 8 lookbacks */ }
},
"analysis": {
"evidence_count": 4,
"unique_symbols": 4,
"diversity": { "score": 1.0 },
"match_quality": { "quality_tag": "strong" },
"seasonality": { /* same_month vs other_months */ },
"forward_outcome": {
"3": { /* returns, tags, commentary */ },
"5": { ... },
"10": { ... },
"15": { ... }
}
},
"matches": [ /* every individual historical analog */ ]
}
Full field-by-field breakdown of every block in Field reference below, and the complete methodology behind these values on the Methodology page.
Browse the symbol universe
Returns a lightweight, cross-lookback browsing index for a given date — every symbol, keyed by lookback period, with enough summary data to triage which symbols are worth fetching the full /analysis file for. This is not the full analysis — no match list, no full distributions, no commentary. Use it to scan the universe quickly; use /analysis/{symbol}-{exchange} for the complete picture.
| Parameter | Values | Description | |
|---|---|---|---|
| country | required | US, CN | Country to browse the symbol universe for. See /v1/countries for supported codes. |
| date | optional | YYYY-MM-DD | Same resolution behaviour as the analysis endpoint — defaults to the most recent available date. |
"https://api.konseki.io/v1/symbols?country=US"
"meta": {
"generated_at": "2026-06-20T06:59:01Z",
"country": "United States",
"timeframe": "1d",
"lookback_periods": [5, 10, 15, 20, 25, 30, 40, 50],
"lookforward_periods": [3, 5, 10, 15]
},
"symbols": {
"10": [
{
"symbol": "AAPL",
"exchange": "NASDAQ",
"name": "Apple Inc.",
"close_prices": [/* sparkline-ready array */],
"latest_data_date": "2026-06-17",
"matches_count": 79,
"earliest_match_year": "2006",
"forward_outcome": {
"3": { "positive_percentage": 0.5696, "average_return": 0.0149 },
/* 5, 10, 15 */
}
},
/* ...remaining symbols at lookback 10 */
],
"15": [ ... ],
/* 15, 20, 25, 30, 40, 50 */
}
}
symbols is keyed by lookback period — each key holds an array of every symbol's summary at that lookback. Per symbol: matches_count and earliest_match_year give a quick read on evidence depth before committing to a full fetch, and the compact forward_outcome summary (positive percentage, average return — not the full distribution) is enough to triage at a glance.
Get the latest available date
Every day's output is a complete, independent snapshot — nothing is overwritten. This endpoint reports the most recent date the engine has run for, so you can confirm freshness or check whether today's data is ready before querying it. Since different countries' markets follow different trading calendars, the latest available date is scoped per country.
| Parameter | Values | Description | |
|---|---|---|---|
| country | required | US, CN | Country to check freshness for. See /v1/countries for supported codes. |
"https://api.konseki.io/v1/metadata?country=US"
"schema_version": "1.0",
"generated_at": "2026-07-14T11:01:30Z",
"country": "United States",
"latest": "2026-07-10"
}
country reflects which country's market calendar this response is scoped to. latest is what the /analysis and /symbols endpoints resolve to for that country when no date parameter is given.
List covered countries
Returns the countries whose equities are included in the current Konseki universe. Use this to check coverage programmatically before querying /analysis or /symbols for a given exchange.
No parameters required.
"https://api.konseki.io/v1/countries"
"countries": [
{ "name": "China", "code": "CN" },
{ "name": "United States", "code": "US" }
]
}
code is the ISO 3166-1 alpha-2 country code. This list reflects coverage as it stands today — new countries are added here automatically as coverage expands, with no changes required on your end.
Errors
Standard HTTP status codes. Error responses are JSON with error, message, and request_id fields. Some errors include extra context, such as parameter, supported_values, limit, or tier.
| 200 | Success. |
| 400 | invalid_request — invalid path or query parameters, such as a missing or unsupported lookback value. |
| 401 | unauthorized — missing, malformed, inactive, or unknown API key. |
| 403 | forbidden — API key is valid but is not allowed to access the requested endpoint. |
| 404 | not_found — endpoint not found, no dated data folder exists, or analysis is unavailable for the requested symbol and lookback. |
| 405 | method_not_allowed — the endpoint requires GET. The response includes an Allow: GET header. |
| 429 | rate_limit_exceeded — request limit reached. The response includes plan. |
| 500 | auth_unavailable or internal_error — API key validation or an unexpected server path failed. |
| 503 | data_unavailable — market data could not be loaded from storage. If this persists, email hello@konseki.io. |
"error": "invalid_request",
"message": "lookback is required.",
"request_id": "a165f32238788df6"
}
Field reference
The four top-level blocks in every /analysis response, and what each contains.
| Field | Description |
|---|---|
| meta.data_through | The market date this analysis reflects. |
| meta.generated_at | Timestamp the output was actually computed — distinct from data_through, since the pipeline runs after close. |
| meta.lookback_periods | The lookback window (in days) this specific file's matches were searched against. |
| benchmark.context | The current symbol's condition across all 8 lookback periods, regardless of which one this file's matches use. |
| analysis.evidence_count | Number of historical matches found for this lookback. |
| analysis.diversity.score | How diverse the match set is across symbols and time — low diversity means matches cluster around one symbol or period. |
| analysis.match_quality | Median match quality across the set, plus a quality_tag of strong / moderate / weak. |
| analysis.seasonality | Cross-symbol comparison of matches in the current calendar month vs. all other months. |
| analysis.forward_outcome.{N} | One block per forward window (3, 5, 10, 15 days) — returns, percentiles, tags, and commentary. |
| forward_outcome.{N}.returns.percentiles | Full P05–P95 distribution of forward returns — not a single predicted value. |
| forward_outcome.{N}.tags | Five machine-readable tags: direction, consistency, reliability, risk, outlier. |
| forward_outcome.{N}.commentary.summary | Natural language summary, written for direct LLM prompt insertion. |
| matches[] | Every individual historical analog — symbol, period, similarity_score, score_components, and its own forward outcome. |
Full explanation of how every score and tag is computed: Methodology →
Quickstart examples
Load into a pandas DataFrame
import requests, pandas as pd
r = requests.get(
"https://api.konseki.io/v1/analysis/AAPL-NASDAQ",
params={"country": "US", "lookback": 15},
headers={"X-API-Key": "ks_live_..."}
)
fwd = r.json()["analysis"]["forward_outcome"]["5"]
dist = pd.Series(fwd["returns"]["percentiles"])
Inject context into an LLM prompt
data = r.json()["analysis"]
prompt = f"""
You are a trading assistant. Use the following
historical market context to answer the user's question.
Evidence: {data["evidence_count"]} historical analogs
Match quality: {data["match_quality"]["quality_tag"]}
Distribution: {data["forward_outcome"]["5"]["returns"]["percentiles"]}
Risk: {data["forward_outcome"]["5"]["tags"]["risk"]}
"""
Query a historical date
"https://api.konseki.io/v1/analysis/AAPL-NASDAQ?country=US&lookback=15&date=2026-01-02"
MCP server
Konseki also ships as an MCP server — a local stdio server that exposes the same public API as MCP tools. It's an adapter, not a separate product: the REST API above is the data source, the MCP server is how MCP-compatible clients (Claude Desktop, Codex, Cursor, Windsurf, and others) can call it directly during a conversation, without you writing any integration code.
Install — Claude Desktop
Add this to your MCP config:
"mcpServers": {
"konseki": {
"command": "npx",
"args": ["-y", "@konseki/mcp"],
"env": {
"KONSEKI_API_KEY": "ks_live_your_api_key"
}
}
}
}
Restart Claude Desktop to pick up the new server. For Codex, Cursor, Windsurf, or other clients, see the setup instructions on the npm and GitHub pages linked below.
Available tools
| Tool | Description |
|---|---|
| get_konseki_analysis | Fetch full historical market context for a symbol and lookback period |
| list_konseki_symbols | List all available symbols in the current coverage universe |
| get_konseki_metadata | Get available lookback periods, forward windows, and last update timestamp |
Ready to start
Create your account. See the data before you build on it.
Start free to explore the output in your dashboard. Upgrade when you need API access.