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. Get a free key by signing up — no credit card required.
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 and reset at midnight UTC. Current limits by tier are published on the Pricing page — at the time of writing, Free is 2,000 requests/day and Pro is 30,000 requests/day. Each call to /analysis/{symbol}-{exchange} counts as one request, regardless of how many forward windows or fields you read from the response.
"error": "rate_limit_exceeded",
"message": "Daily request limit reached. Resets at midnight UTC.",
"limit": 2000,
"tier": "free"
}
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 Coverage page URLs.
Parameters
| Parameter | Values | Description | |
|---|---|---|---|
| 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?lookback=15"
Example response (trimmed)
"meta": {
"data_through": "2026-06-17",
"timeframe": "1d",
"universe": "sp500",
"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 | |
|---|---|---|---|
| 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"
"meta": {
"generated_at": "2026-06-20T06:59:01Z",
"universe": "sp500",
"timeframe": "1d",
"lookback_periods": [5, 10, 15, 20, 25, 30, 40, 50],
"lookforward_periods": [3, 5, 10, 15]
},
"symbols": {
"5": [
{
"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 5 */
],
"10": [ ... ],
/* 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.
Discover available dates
Every day's output is a complete, independent snapshot — nothing is overwritten. This endpoint lists which dates actually exist, so you can validate a date before querying it, or iterate over history for backtesting without guessing at the range.
No parameters required.
"https://api.konseki.io/v1/metadata"
"schema_version": "1.0",
"generated_at": "2026-06-20T07:00:00Z",
"latest": "2026-06-17",
"dates": ["2026-06-17", "2026-06-16", ..., "2026-01-02"]
}
latest is what the /analysis and /symbols endpoints resolve to when no date parameter is given. dates lists every available date, most recent first.
Errors
Standard HTTP status codes. Error responses are JSON with error and message fields, matching the format shown in Rate limits above.
| 200 | Success. |
| 400 | Invalid parameters — e.g. an unsupported lookback value. |
| 401 | Missing or invalid API key. |
| 404 | Symbol not found, or no data exists for the requested date. |
| 429 | Daily rate limit exceeded. Resets at midnight UTC. |
| 500 | Server error. If this persists, email hello@konseki.io. |
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={"lookback": 15},
headers={"X-API-Key": "ea_live_..."}
)
fwd = r.json()["analysis"]["forward_outcome"]["5"]
dist = pd.Series(fwd["returns"]["percentiles"])
Inject context into an LLM prompt
context = fwd["commentary"]["summary"]
prompt = f"""
Historical context for AAPL (5-day forward):
\${context}
"""
Query a historical date
"https://api.konseki.io/v1/analysis/AAPL-NASDAQ?lookback=15&date=2026-01-02"
Ready to start
Get your API key. Free, no credit card required.
2,000 requests/day on Free — enough to evaluate the product properly.