Clarity Kpi API
The kpi API from Clarity — 1 operation(s) for kpi.
The kpi API from Clarity — 1 operation(s) for kpi.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/onclarity-com:onclarity-com-kpi-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Fast Kpi API
version: 0.1.0
tags:
- name: kpi
paths:
/api/v1/kpi:
post:
tags:
- kpi
summary: Build Kpi
description: 'Compute a single KPI value, its baseline, and the delta between them.
Reuses the `/tables` aggregation engine internally (see `kpi_builder`). The
current period is defined by `filters` (page-level filters plus the widget''s
own `ds`); the baseline is computed server-side per `baseline.type`.
Args:
body: Filters, optional search query, the aggregation, and the baseline mode.
Returns:
The value, the baseline (null when unavailable or `type == ''none''`), and
the signed delta (null when there''s no baseline to compare against).
Raises:
HTTPException: 422 when a non-count aggregation is missing its `field`.'
operationId: build_kpi_api_v1_kpi_post
security:
- HTTPBearer: []
parameters:
- name: x-request-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Request-Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KpiRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/KpiResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
KpiAggregation:
properties:
operation:
type: string
enum:
- count
- sum
- avg
- median
- min
- max
- cardinality
- top_1
title: Operation
field:
anyOf:
- type: string
- type: 'null'
title: Field
description: Field to aggregate. Ignored for `count`; required for the other operations.
type: object
required:
- operation
title: KpiAggregation
description: Which metric to compute.
KpiDelta:
properties:
absolute:
type: number
title: Absolute
percent:
anyOf:
- type: number
- type: 'null'
title: Percent
direction:
type: string
enum:
- up
- down
- flat
title: Direction
type: object
required:
- absolute
- percent
- direction
title: KpiDelta
KpiResponse:
properties:
value:
anyOf:
- type: number
- type: 'null'
title: Value
baseline:
anyOf:
- $ref: '#/components/schemas/KpiBaselineResult'
- type: 'null'
delta:
anyOf:
- $ref: '#/components/schemas/KpiDelta'
- type: 'null'
range:
anyOf:
- $ref: '#/components/schemas/src__service__kpi_builder__DateRange'
- type: 'null'
overrides_page_range:
type: boolean
title: Overrides Page Range
default: false
type: object
required:
- value
title: KpiResponse
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
KpiWindow:
properties:
type:
type: string
const: relative
title: Type
default: relative
unit:
type: string
enum:
- day
- week
- month
- quarter
- year
title: Unit
default: week
count:
type: integer
minimum: 1.0
title: Count
description: Trailing length in units.
default: 1
offset:
type: integer
title: Offset
default: 0
align:
type: string
enum:
- complete
- to_date
title: Align
default: complete
week_start:
type: string
enum:
- monday
- sunday
title: Week Start
default: monday
anchor:
type: string
enum:
- today
- dashboard_end
title: Anchor
default: today
override_page_range:
type: boolean
title: Override Page Range
description: Echoed back so the card can badge itself — a widget that ignores the page date range must say so, or it breaks the filter mental model.
default: true
type: object
title: KpiWindow
description: 'The card''s own period, independent of the dashboard''s date range.
Without this a week-over-week card is hostage to the page: `previous_period`
shifts the range back by its own length, so the card only says "week over
week" when the whole dashboard is set to seven days.'
src__service__kpi_builder__DateRange:
properties:
from:
type: string
title: From
to:
type: string
title: To
type: object
required:
- from
- to
title: DateRange
description: Inclusive date window, `YYYY-MM-DD`.
KpiBaselineResult:
properties:
type:
type: string
enum:
- previous_period
- previous_calendar_month
- previous_quarter
- same_period_last_year
- custom_range
- fixed_number
- relative
title: Type
value:
anyOf:
- type: number
- type: 'null'
title: Value
range:
anyOf:
- $ref: '#/components/schemas/src__service__kpi_builder__DateRange'
- type: 'null'
type: object
required:
- type
- value
title: KpiBaselineResult
KpiRequest:
properties:
filters:
items:
$ref: '#/components/schemas/QueryFilter'
type: array
title: Filters
query:
anyOf:
- type: string
- type: 'null'
title: Query
aggregation:
$ref: '#/components/schemas/KpiAggregation'
baseline:
$ref: '#/components/schemas/KpiBaseline'
window:
anyOf:
- $ref: '#/components/schemas/KpiWindow'
- type: 'null'
type: object
required:
- aggregation
title: KpiRequest
description: Request body for `POST /api/v1/kpi`. `project` comes from the auth token.
DateRange-Input:
properties:
from:
type: string
title: From
to:
type: string
title: To
type: object
required:
- from
- to
title: DateRange
description: Inclusive date window, `YYYY-MM-DD`.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
QueryFilter:
properties:
type:
anyOf:
- type: string
const: exists
- type: string
const: list
- type: string
const: nested
- type: string
const: range
- type: string
const: text
title: Type
key:
type: string
title: Key
values:
anyOf:
- items:
type: string
type: array
- items:
type: integer
type: array
- items:
additionalProperties: true
type: object
type: array
- type: string
- type: 'null'
title: Values
min:
anyOf:
- type: string
- type: integer
- type: number
- type: 'null'
title: Min
max:
anyOf:
- type: string
- type: integer
- type: number
- type: 'null'
title: Max
operator:
anyOf:
- type: string
const: eq
- type: string
const: neq
- type: string
const: contains
title: Operator
default: eq
generated:
type: boolean
title: Generated
default: false
type: object
required:
- type
- key
title: QueryFilter
KpiBaseline:
properties:
type:
type: string
enum:
- previous_period
- previous_calendar_month
- previous_quarter
- same_period_last_year
- custom_range
- fixed_number
- relative
- none
title: Type
default: none
range:
anyOf:
- $ref: '#/components/schemas/DateRange-Input'
- type: 'null'
description: Window for `custom_range`.
value:
anyOf:
- type: number
- type: 'null'
title: Value
description: User-entered baseline for `fixed_number`.
unit:
anyOf:
- type: string
enum:
- day
- week
- month
- quarter
- year
- type: 'null'
title: Unit
offset:
type: integer
title: Offset
default: -1
align:
anyOf:
- type: string
enum:
- complete
- to_date
- type: 'null'
title: Align
week_start:
anyOf:
- type: string
enum:
- monday
- sunday
- type: 'null'
title: Week Start
type: object
title: KpiBaseline
description: Baseline to compare the value against.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
HTTPBasic:
type: http
scheme: basic