> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keplerinsights.us/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/distribution

> Universe-wide score distribution: histograms, rating mix, profile split.

The shape of the entire scored universe. Use it to position any individual score against everyone — "is 67 in the top 10%?" — and to render aggregate dashboards.

## When to use it

* Render a histogram of scores with your target's position marked.
* Sanity-check whether a tier (`KI-1+`) is rare or common in the current universe.
* Compare growth vs. established profile distributions.

## Response

```json theme={null}
{
  "pipeline_version": "v1",
  "universe": {
    "count": 540,
    "mean": 54.3, "p50": 53.5, "p90": 76.0,
    "stddev": 16.8, "min": 28.7, "max": 79.4,
    "composite_hist": [
      { "range": "0-5",    "count": 0 },  { "range": "5-10",   "count": 0 },
      { "range": "10-15",  "count": 0 },  { "range": "15-20",  "count": 2 },
      { "range": "20-25",  "count": 4 },  { "range": "25-30",  "count": 8 },
      { "range": "30-35",  "count": 18 }, { "range": "35-40",  "count": 32 },
      { "range": "40-45",  "count": 54 }, { "range": "45-50",  "count": 78 },
      { "range": "50-55",  "count": 92 }, { "range": "55-60",  "count": 88 },
      { "range": "60-65",  "count": 68 }, { "range": "65-70",  "count": 48 },
      { "range": "70-75",  "count": 28 }, { "range": "75-80",  "count": 14 },
      { "range": "80-85",  "count": 6 },  { "range": "85-90",  "count": 0 },
      { "range": "90-95",  "count": 0 },  { "range": "95-100", "count": 0 }
    ],
    "scale_premium_hist": [
      { "range": "0-1",   "count": 380 },
      { "range": "1-2",   "count": 88 },
      ...
    ],
    "rating_dist": {
      "KI-1+": 6, "KI-1": 22, "KI-2+": 78, "KI-2": 142,
      "KI-3":  198, "KI-4": 78, "KI-5": 16
    },
    "profile_split": { "growth": 414, "established": 116, "unclassified": 10 }
  }
}
```

## Bin granularity

* **Composite:** 20 bins of width 5 (`0-5`, `5-10`, …, `95-100`).
* **Scale premium:** 12 bins of width 1 (`0-1`, `1-2`, …, `11-12`).

If you need finer resolution, paginate `/v1/score/{domain}/history` over a representative sample of domains and compute it yourself. The histogram here is fixed-shape so we can cache it cheaply.

## `pipeline_version`

The universe is filtered to records produced under the current pipeline version (e.g. `v1`). When Kepler ships a major engine change, this version bumps and the universe is re-seeded as new records land. Don't compare counts across pipeline versions — they're effectively different datasets.

## Caching

Served from a 10-minute in-memory cache. Two calls in the same minute will likely return the same `count` even if a new scoring run lands between them.


## OpenAPI

````yaml GET /v1/distribution
openapi: 3.1.0
info:
  title: Kepler Insights API
  version: 1.0.0
  summary: Curated company-scoring intelligence over a 67-signal engine.
  description: >
    The Kepler Insights API exposes a curated subset of the Kepler scoring
    engine

    over a stable REST surface. Every score is a composite over 67 signals
    organized

    into 4 buckets (Team & Structure, Market Position, Momentum & Tailwinds,

    Financial Health), with a separate scale premium that lifts established

    companies whose underlying fundamentals justify a higher tier.


    **Authentication.** All requests require a single header: `X-API-Key`.

    Keys are issued from the developer console at
    `https://console.keplerinsights.us`.


    **Sandbox.** Test keys prefixed `ki_test_` accept only the four canned

    domains (`acme.test`, `unicorn.test`, `struggling.test`, `cohort.test`),

    never invoke fetchers, and return deterministic responses tagged with

    `mode: sandbox`. Live keys prefixed `ki_live_` reject test domains and

    run against the real engine.


    **Cold vs cached.** `GET /v1/score/{domain}` is always cached (404 if no

    recent record exists). `POST /v1/score` decides per-call based on your

    tier's freshness window: a fresh record returns inline (`200`), a stale

    or missing one queues a cold pipeline run and returns `202` with a

    `job_id` to poll. Cold spend is bounded by per-tier monthly caps +

    circuit breakers.
  contact:
    name: Kepler Insights API support
    email: noah@keplerinsights.us
  license:
    name: Proprietary
servers:
  - url: https://api.keplerinsights.us
    description: Production
security:
  - apiKey: []
tags:
  - name: scoring
    description: Score a company and retrieve the latest result.
  - name: history
    description: Time-series of past scoring runs for a single company.
  - name: company
    description: Per-company analytics (cohort, confidence).
  - name: universe
    description: Distribution + movers across the full scored universe.
  - name: meta
    description: Signal manifest + caller usage + async job tracking.
paths:
  /v1/distribution:
    get:
      tags:
        - universe
      summary: Universe-wide score distribution.
      description: |
        Returns the composite + scale premium histograms, KI-rating mix, and
        growth/established profile split across every domain Kepler has scored
        on the current pipeline version. Use to position any single company
        against the full universe rather than just its cohort.
      operationId: getDistribution
      responses:
        '200':
          description: Universe distribution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistributionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DistributionResponse:
      type: object
      properties:
        mode:
          type: string
        pipeline_version:
          type: string
          example: v1
        universe:
          type: object
          properties:
            count:
              type: integer
            mean:
              type: number
            p50:
              type: number
            p90:
              type: number
            stddev:
              type: number
            min:
              type: number
            max:
              type: number
            composite_hist:
              $ref: '#/components/schemas/Histogram'
            scale_premium_hist:
              $ref: '#/components/schemas/Histogram'
            rating_dist:
              type: object
              additionalProperties:
                type: integer
            profile_split:
              type: object
              properties:
                growth:
                  type: integer
                established:
                  type: integer
                unclassified:
                  type: integer
    Histogram:
      type: array
      items:
        type: object
        properties:
          range:
            type: string
            example: 60-65
          count:
            type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: unauthorized
        message:
          type: string
        reason:
          type: string
          description: Additional context for rate-limit responses.
  responses:
    Unauthorized:
      description: Missing or invalid `X-API-Key`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        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.

````