Getting started

Authenticate, make your first call, and learn the four conventions the whole API follows.

The Kometrics API serves the same numbers the dashboard shows, computed by the same engine. It is read only: every endpoint is a GET, and nothing you can call will change your book.

All requests go to https://kometrics.com/api/v1, over HTTPS.

curl https://kometrics.com/api/v1/account \
  -H "Authorization: Bearer ko_your_api_key"

Authentication

Create a key under Settings, then API keys. Keys start with ko_ and are shown once at creation, so store it somewhere safe before closing the dialog.

Send it as a bearer token. HTTP Basic also works with the key as the username and an empty password, which lets ChartMogul client libraries authenticate against Kometrics unchanged.

A key is scoped to exactly one workspace and serves that workspace and nothing else. Revoking a key in Settings takes effect on the next request.

curl https://kometrics.com/api/v1/account \
  -H "Authorization: Bearer ko_your_api_key"

Conventions

Four rules hold across every endpoint, so once you have read them the rest of the reference is just field names.

Rule	Detail
Money is in cents	An `mrr` of `580000` is $5,800.00, in the workspace currency reported by /account.
Dates are YYYY-MM-DD	Both in query parameters and in responses. Times of day never appear.
Lists are cursor paginated	Responses carry `entries`, `has_more`, and a `cursor` when there is another page.
Percentages are numbers	A `customer-churn-rate` of `2.83` means 2.83%, not 0.0283.

Every date is resolved in your workspace timezone, the one /account reports, including daylight saving changes. A day in a query parameter means that day where your business is, and the same instant can land on different dates for workspaces in different zones.

Pagination

Endpoints that return entries accept per_page (1 to 200, default 50) and an opaque cursor. Read has_more, and when it is true pass the returned cursor back to get the next page.

The per customer sub-resources are the exception: they return a customer's whole history in one response and always report has_more: false.

async function everyActivity(key) {
  const out = []
  let cursor = null
  do {
    const url = new URL("https://kometrics.com/api/v1/activities")
    url.searchParams.set("per_page", "200")
    if (cursor) url.searchParams.set("cursor", cursor)
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } })
    const page = await res.json()
    out.push(...page.entries)
    cursor = page.has_more ? page.cursor : null
  } while (cursor)
  return out
}

OpenAPI

A machine-readable OpenAPI 3.1 description of every endpoint is served unauthenticated, so connector and MCP tooling can configure itself before it has a key.

GET/api/v1/openapi.json

curl https://kometrics.com/api/v1/openapi.json