Score a company. Cached returns inline, cold returns a job.
Endpoints
POST /v1/score
Score a company. Cached returns inline; cold returns a job to poll.
POST
Score a company. Cached returns inline, cold returns a job.
The primary scoring entry point. Returns the latest score for
Branch on the response: if the body has
domain from cache when a stored record is within your tier’s freshness window, or starts a cold scoring job when no fresh record exists.
Two response shapes
- HTTP 200 — a cached score is available. Returned inline; ready to use.
- HTTP 202 — no fresh record. The server has started a cold scoring run and returned a
job_id. PollGET /v1/jobs/{job_id}untilstatus: "complete".
When you’ll see each path
- Cached (200) — the dominant path. Most calls hit it; tier-determined freshness windows are designed so that customer traffic mostly reuses recent work.
- Cold (202) — first time you’ve ever asked for
domain, or the most recent record is older than your tier’s window.
| Tier | Window |
|---|---|
| Free | 7 days (sandbox only — Free can’t run live cold) |
| Starter | 24 hours |
| Growth | 6 hours |
| Scale | 1 hour |
| Enterprise | 15 minutes |
Example (Python SDK)
The official SDK handles both shapes transparently.score() blocks until the score is ready, polling internally on the cold path.
Example (curl, manual polling)
composite_score, you have the score inline. If it has job_id, queue a poll loop on the poll_url.
Field notes
composite_scoreis 0–100, not 0–10. Easy mistake when reading.scale_premiumis a separate additive bonus (up to ~12 pts). It’s already applied tocomposite_score; the field is broken out so you can show “47.0 composite + 4.1 scale premium” if you want.rankis computed against the full universe Kepler has ever scored, not just the active cohort. Use/v1/company/{domain}/cohortfor sector-matched comparison.x_kepler.cache_statusis"cached"on every score body, including the one you fetch after a job completes — the fresh cold-pipeline result is written to cache before the response shape is constructed. The enum is reserved for a future sync-cold response shape; today only"cached"is emitted.waitparameter is accepted but ignored. Cold = async, always. The parameter is preserved so older client code doesn’t break.
Sandbox behavior
ki_test_ keys against the 4 canned domains (acme.test, unicorn.test, struggling.test, cohort.test) always return inline 200. Sandbox has no cold path — there’s nothing to queue. This means production code paths that branch on 202 won’t be exercised in the sandbox. Test the polling path against a fresh live domain in staging before relying on it.Authorizations
Live keys are prefixed ki_live_, test keys ki_test_. Issue + revoke
keys at https://console.keplerinsights.us. Never embed a key in client-side
code — every endpoint is backend-to-API only.
Body
application/json
Response
Cached score (fresh under your tier's window).
Available options:
KI-1+, KI-1, KI-2+, KI-2, KI-3, KI-4, KI-5 Required range:
0 <= x <= 100The 4 KI buckets. Each is 0–100.
Present and = sandbox only with a ki_test_ key.
Up to ~12 pts for established mega-caps; up to ~6 pts for growth profile.
Required range:
0 <= x <= 12Caller-facing metadata. Stable across versions.

