> ## 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/usage > Your current monthly usage counters and tier limits. A read of where you stand against your tier's quota for the current calendar month. **Does not increment** any counter — checking your balance shouldn't move it. ## When to use it * Render a dashboard with "X / 250 cold calls used this month". * Detect a runaway script before it hits the per-account 24h circuit breaker. * Confirm an overage rate or freshness window without paginating any docs. ## Response ```json theme={null} { "user_id": "uuid-of-your-account", "period": "2026-05", "tier": "growth", "total_calls": 1042, "cold_calls": 38, "cached_calls": 1004, "last_reset": "2026-05-01T00:00:00Z", "next_reset": "2026-06-01T00:00:00Z", "tier_limits": { "cached_calls_included": 5000, "cold_calls_included": 250, "freshness_window_hours": 6 } } ``` ## Counter semantics * **`total_calls`** = `cached_calls` + `cold_calls`. Both meters count. * **`cold_calls`** is what bills against your tier's included monthly budget. When this reaches `tier_limits.cold_calls_included`, further `POST /v1/score` calls that would trigger a cold run return `429 cold_budget_exhausted` until the next monthly reset. * **`null` in `tier_limits`** means unmetered (Enterprise / admin). * **No overage counter in v1.0.** Metered overage is on the v1.5 roadmap; when it ships, an additional counter will appear here for accounts that opt in. ## Zero-state If you haven't made any calls yet this period (or it's the first of the month and counters just reset), every counter reads `0` and `last_reset` reads the current period's start. There's no `404` for "never called the API" — we treat that as zero state. ## Counter reset Counters reset on the first of the month at `00:00 UTC`. Reset is lazy — the first call after the rollover sets `last_reset` to the new period start and zeroes the per-period meters. Historical periods are retained 14 months for billing reconciliation but are not exposed via this endpoint. ## Why no increment Stripe's `/v1/subscription` doesn't bill you for reading your subscription state. Same principle. Calling `/v1/usage` is free — go nuts. ## OpenAPI ````yaml GET /v1/usage 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/usage: get: tags: - meta summary: Your current monthly usage and tier limits. description: | Counters for the current calendar month. Does NOT increment usage (mirrors Stripe's `/v1/subscription` no-side-effect pattern). Returns a zero-counter shape if you haven't called the API yet this period. operationId: getUsage responses: '200': description: Usage state. content: application/json: schema: $ref: '#/components/schemas/UsageResponse' '401': $ref: '#/components/responses/Unauthorized' components: schemas: UsageResponse: type: object properties: mode: type: string user_id: type: string period: type: string example: 2026-05 tier: type: string total_calls: type: integer cold_calls: type: integer cached_calls: type: integer last_reset: type: string format: date-time next_reset: type: string format: date-time tier_limits: $ref: '#/components/schemas/TierLimits' TierLimits: type: object properties: cached_calls_included: type: integer nullable: true description: null = unmetered (Enterprise / admin). cold_calls_included: type: integer nullable: true description: >- Monthly cold-call budget. v1.0 is flat-only: exceeding this returns 429 cold_budget_exhausted. freshness_window_hours: type: number 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. ````