Skip to main content
POST
/
v1
/
score
Score a company (cold or cached).
curl --request POST \
  --url https://api.keplerinsights.us/v1/score \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "domain": "stripe.com",
  "force_fresh": false,
  "wait": true
}
'
{
  "domain": "<string>",
  "scored_at": "2023-11-07T05:31:56Z",
  "ki_rating": "KI-1+",
  "composite_score": 50,
  "buckets": {
    "team_structure": 50,
    "market_position": 50,
    "momentum_tailwinds": 50,
    "financial_health": 50
  },
  "mode": "<string>",
  "scale_premium": 6,
  "rank": {
    "percentile": 50,
    "cohort_size": 1
  },
  "x_kepler": {
    "tier": "free",
    "cache_status": "cached",
    "freshness_window_hours": 123
  }
}

Documentation Index

Fetch the complete documentation index at: https://keplerinsights.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The primary scoring entry point. Returns the latest score for domain — either from cache (if a stored record is within your tier’s freshness window) or by running a fresh cold pipeline.

​
When to use it

  • You want the score for a specific company right now.
  • You don’t already have a stored record, or it’s stale for your purposes.
  • You’re on Free / Starter — sync is the only path available.
If you have a job_id from an earlier async start, use GET /v1/jobs/{job_id} instead.

​
Behavior

​
Example (Python)

import requests

r = requests.post(
    "https://api.keplerinsights.us/v1/score",
    headers={"X-API-Key": "ki_live_..."},
    json={"domain": "stripe.com"},
    timeout=70,  # >60s cold budget + headroom
)
score = r.json()
print(f"{score['domain']}: {score['ki_rating']} ({score['composite_score']:.1f})")

​
Example (curl, with async fallback)

# Async on Growth+
curl -X POST https://api.keplerinsights.us/v1/score?wait=false \
  -H "X-API-Key: ki_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'

# → 202 { "job_id": "...", "status": "pending", "poll_url": "/v1/jobs/..." }

​
Field notes

  • composite_score is 0–100, not 0–10. Easy mistake when reading.
  • scale_premium is a separate additive bonus (up to ~12 pts). It’s already applied to composite_score; the field is broken out so you can show “47.0 composite + 4.1 scale premium” if you want.
  • rank is computed against the full universe Kepler has ever scored, not just the active cohort. Use /v1/company/{domain}/cohort for sector-matched comparison.
  • x_kepler.cache_status is "cached" or "cold" — use it to decide whether to surface a “last scored 4 hours ago” note in your UI.

Authorizations

​
X-API-Key
string
header
required

Live keys are prefixed ki_live_, test keys ki_test_. Issue + revoke keys at https://api.keplerinsights.us. Never embed a key in client-side code — every endpoint is backend-to-API only.

Query Parameters

​
wait
enum<string>
default:true

Set to false for the async path (Growth+). Body field wait also accepted.

Available options:
true,
false

Body

application/json
​
domain
string
required
Example:

"stripe.com"

​
force_fresh
boolean
default:false

Enterprise-only. Forces a cold run even if a fresh record exists.

​
wait
boolean
default:true

Mirrors ?wait= query. Body wins if both set.

Response

Score (sync). Cached or fresh-cold.

​
domain
string
required
​
scored_at
string<date-time>
required
​
ki_rating
enum<string>
required
Available options:
KI-1+,
KI-1,
KI-2+,
KI-2,
KI-3,
KI-4,
KI-5
​
composite_score
number<float>
required
Required range: 0 <= x <= 100
​
buckets
object
required

The 4 KI buckets. Each is 0–100.

​
mode
string

Present and = sandbox only with a ki_test_ key.

​
scale_premium
number<float>

Up to ~12 pts for established mega-caps; up to ~6 pts for growth profile.

Required range: 0 <= x <= 12
​
rank
object
​
x_kepler
object

Caller-facing metadata. Stable across versions.