> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Marketing Agent KPI values (web apps)
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Returns what each KPI in the Marketing Agent's plan measures right now, read from the app's analytics.
`values` is in the same order as `kpis` in [Get Marketing Agent state (web apps)](/api-reference/get-marketing-agent-state-web-apps), so match the two by position rather than by name. A plan with no KPIs yet returns an empty list. Read `state` before `value`: a KPI that can't be measured has no `value` rather than a `0`.
Values can be up to an hour old. They're read again when the KPIs change, and on every call while any KPI is `not_tracked` or `unavailable`, so a newly recorded event shows up on the next call.
This is limited to 120 requests a minute per app for each workspace's personal API keys, so every personal API key in a workspace shares one allowance, and each workspace API key has its own, across every Marketing Agent endpoint. Some workspaces have a different limit.
This endpoint accepts a personal API key belonging to a user with editor access to the app and an editor role in its workspace, or a workspace API key, which acts as the workspace owner. Read-only tokens and keys are refused.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/cmo/kpi-values
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/cmo/kpi-values:
get:
summary: Get Marketing Agent KPI values (web apps)
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Returns what each KPI in the Marketing Agent's plan measures right now,
read from the app's analytics.
`values` is in the same order as `kpis` in [Get Marketing Agent state
(web apps)](/api-reference/get-marketing-agent-state-web-apps), so match
the two by position rather than by name. A plan with no KPIs yet returns
an empty list. Read `state` before `value`: a KPI that can't be measured
has no `value` rather than a `0`.
Values can be up to an hour old. They're read again when the KPIs
change, and on every call while any KPI is `not_tracked` or
`unavailable`, so a newly recorded event shows up on the next call.
This is limited to 120 requests a minute per app for each workspace's
personal API keys, so every personal API key in a workspace shares one
allowance, and each workspace API key has its own, across every
Marketing Agent endpoint. Some workspaces have a different limit.
This endpoint accepts a personal API key belonging to a user with
editor access to the app and an editor role in its workspace, or a
workspace API key, which acts as the workspace owner. Read-only tokens
and keys are refused.
operationId: get_cmo_kpi_values_api_apps__app_id__cmo_kpi_values_get
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app.
title: App Id
description: ID of the app.
example: 6820f3a4e7b91d003c45a1f2
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/KpiValuesResponse'
'401':
description: Missing or invalid credentials.
'403':
description: >-
You don't have editor access to this app or an editor role in its
workspace, the app is a mobile app, Superagent is turned off for the
workspace, or your token or key is read-only. Setup, chat,
generation and enabling autonomy also return
`app_marketing_not_allowed` when the app's owning workspace has the
FERPA designation. Historical reads, reset and disabling autonomy
remain available.
'404':
description: App not found.
'429':
description: Rate limit exceeded.
security:
- PersonalAccessTokenAuth:
- full_access
- WorkspaceApiKeyAuth:
- full_access
- WorkspaceApiKeyBearerAuth:
- full_access
components:
schemas:
KpiValuesResponse:
properties:
values:
items:
$ref: '#/components/schemas/KpiValue'
type: array
title: Values
description: >-
One entry per KPI, in the same order as `kpis` in [Get Marketing
Agent state (web
apps)](/api-reference/get-marketing-agent-state-web-apps).
example:
- first_seen: '2026-08-22T10:00:00Z'
state: measured
value: 42
window_days: 7
type: object
required:
- values
title: KpiValuesResponse
KpiValue:
properties:
state:
type: string
enum:
- measured
- awaiting_data
- window_too_short
- not_tracked
- unbound
- unavailable
title: State
description: >-
What the value means. `measured` is a full measurement.
`awaiting_data` means the event started being recorded inside the
KPI's window, so `value` covers less than the whole window.
`window_too_short` means a retention KPI's event is recorded but no
user has been around for `n` days yet. `not_tracked` means the app
doesn't record the KPI's event yet. `unbound` means the KPI has no
`metric`, so there's nothing to measure. `unavailable` means the
analytics read failed, so try again later.
example: measured
value:
anyOf:
- type: number
- type: 'null'
title: Value
description: >-
The measured number, present only when `state` is `measured` or
`awaiting_data`. A count for most KPIs, and a percentage rounded to
one decimal place for a `retention_dn` KPI.
example: 42
unit:
anyOf:
- type: string
const: percent
- type: 'null'
title: Unit
description: >-
`percent` on a measured `retention_dn` KPI. Absent otherwise, where
`value` is a count.
example: percent
first_seen:
anyOf:
- type: string
- type: 'null'
title: First Seen
description: >-
When the app first recorded the KPI's event, as a UTC ISO 8601
timestamp. Absent when `state` is `not_tracked`, `unbound`, or
`unavailable`, except on a `retention_dn` KPI that isn't tracked,
where it's `null`.
example: '2026-08-22T10:00:00Z'
window_days:
anyOf:
- type: integer
- type: 'null'
title: Window Days
description: >-
Number of days `value` counts over, on a KPI that isn't
`retention_dn`. Absent otherwise.
example: 7
'n':
anyOf:
- type: integer
- type: 'null'
title: 'N'
description: >-
Day a `retention_dn` KPI measures the return at. Absent on other
KPIs.
example: 7
cohort:
anyOf:
- type: integer
- type: 'null'
title: Cohort
description: >-
Number of users a measured `retention_dn` KPI's percentage is out
of. Absent otherwise.
example: 120
type: object
required:
- state
title: KpiValue
description: What one KPI measures right now.
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: >-
Personal access token, sent as `Authorization: Bearer `. Each
operation lists the permission it needs: `read_only` or `full_access`. A
full-access token can call every operation. A read-only token can call
only the operations that list `read_only`; anything else returns 403
`read_only_credential_route_not_allowed`.
WorkspaceApiKeyAuth:
type: apiKey
in: header
name: api_key
description: >-
Workspace API key, sent as `api_key: `. Each operation that accepts
one lists what the key needs: a permission, `read_only` or
`full_access`, like a personal access token, or a scope. A key without
the scope gets 403 `workspace_api_key_scope_required`.
WorkspaceApiKeyBearerAuth:
type: http
scheme: bearer
description: >-
Workspace API key, sent as `Authorization: Bearer `. Accepted
wherever `api_key` is, with the same permission.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.