> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to SimpleKPI

The SimpleKPI connector lets your AI agent act in each user's SimpleKPI account. Each user connects their own SimpleKPI access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 38 tools.

**Authentication:** Bearer Token
**Categories:** Analytics
**Tools:** 38: 19 read, 13 write, 6 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=SIMPLEKPI)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the SimpleKPI connection

   In **AgentKit > Connections**, create a SimpleKPI connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'simplekpi'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize SimpleKPI:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'simplekpi_breakdown_items_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "simplekpi"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize SimpleKPI:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="simplekpi_breakdown_items_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their SimpleKPI credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'simplekpi_breakdown_item_get',
  toolInput: {
    item_id: 1234,
  },
  connector: 'simplekpi',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="simplekpi_breakdown_item_get",
    tool_input={
        "item_id": 1234,
    },
    connection_name="simplekpi",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `simplekpi_breakdown_item_get`

Get Breakdown Item · Read-only

Get one breakdown item by ID. Returns the item object.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`integer`, required): ID of the breakdown item. Example: 1234.

Example input: `{"item_id":1234}`

### `simplekpi_breakdown_items_list`

List Breakdown Items · Read-only

List the breakdown items (the people, teams, products or regions a KPI is split by). Returns item IDs to use as source_id on KPI entries. Use simplekpi_breakdown_item_get for one item.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.

Example input: `{}`

### `simplekpi_category_kpi_get`

Get KPI in Category · Read-only

Get one KPI from a category. Returns the KPI object; a KPI from another category returns 404.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`integer`, required): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `kpi_id` (`integer`, required): ID of the KPI. Example: 1234.

Example input: `{"category_id":5478,"kpi_id":1234}`

### `simplekpi_category_kpis_list`

List KPIs in Category · Read-only

List the KPIs in one category, a page at a time. Returns KPI objects. Use simplekpi_kpis_list for every KPI.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`integer`, required): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.

Example input: `{"category_id":5478}`

### `simplekpi_kpi_categories_list`

List KPI Categories · Read-only

List the KPI categories (groups of KPIs). Returns category objects with ID, name and sort order. Use simplekpi_category_kpis_list for the KPIs in one category.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.

Example input: `{}`

### `simplekpi_kpi_category_get`

Get KPI Category · Read-only

Get one KPI category by ID. Returns the category object. Get IDs from simplekpi_kpi_categories_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`integer`, required): ID of the category. Example: 1234.

Example input: `{"category_id":1234}`

### `simplekpi_kpi_entries_list`

List KPI Entries · Read-only

List raw KPI entries (actuals, targets, notes per date), filtered by KPI, user, breakdown item and date range, a page at a time. Returns entry objects. Use simplekpi_report_get for values aggregated per period.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `date_from` (`string`, optional): Earliest entry date to include. Example: 2026-07-01T00:00:00.
- `date_to` (`string`, optional): Latest entry date to include. Example: 2026-07-31T00:00:00.
- `kpi_id` (`integer`, optional): Only entries for this KPI. Example: 1234.
- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.
- `source_id` (`integer`, optional): Only entries for this breakdown source. Example: 0.
- `user_id` (`integer`, optional): Only entries recorded against this user. Example: 42.

Example input: `{}`

### `simplekpi_kpi_entry_get`

Get KPI Entry · Read-only

Get one KPI entry by ID. Returns the entry object. Get IDs from simplekpi_kpi_entries_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `entry_id` (`integer`, required): ID of the entry. Example: 1234.

Example input: `{"entry_id":1234}`

### `simplekpi_kpi_frequencies_list`

List KPI Frequencies · Read-only

List the frequencies a KPI can use (daily, weekly, monthly...). Returns frequency IDs (D, W, M, Q, Y) and names to use as frequency_id.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `simplekpi_kpi_frequency_get`

Get KPI Frequency · Read-only

Get one frequency by its code. Returns the frequency's ID and name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `frequency_id` (`string`, required): Frequency code, for example W (case sensitive). Example: W.

Example input: `{"frequency_id":"<frequency_id>"}`

### `simplekpi_kpi_get`

Get KPI · Read-only

Get one KPI by ID. Returns the KPI object. Get IDs from simplekpi_kpis_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `kpi_id` (`integer`, required): ID of the KPI. Example: 1234.

Example input: `{"kpi_id":1234}`

### `simplekpi_kpi_icon_get`

Get KPI Icon · Read-only

Get one KPI icon by ID. Returns the icon object.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `icon_id` (`integer`, required): ID of the icon. Example: 1234.

Example input: `{"icon_id":1234}`

### `simplekpi_kpi_icons_list`

List KPI Icons · Read-only

List the icons a KPI can show. Returns icon IDs and names to use as icon_id.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `simplekpi_kpi_unit_get`

Get KPI Unit · Read-only

Get one unit by ID. Returns the unit object. Get IDs from simplekpi_kpi_units_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `unit_id` (`integer`, required): ID of the unit. Example: 1234.

Example input: `{"unit_id":1234}`

### `simplekpi_kpi_units_list`

List KPI Units · Read-only

List the units that format KPI values (currency, percentage, number). Returns unit IDs and formats to use as unit_id.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.

Example input: `{}`

### `simplekpi_kpis_list`

List KPIs · Read-only

List the KPIs on the account, a page at a time. Returns KPI objects with ID, name, category, unit, frequency, direction and default target. Use simplekpi_category_kpis_list for one category and simplekpi_kpi_get for one KPI.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.

Example input: `{}`

### `simplekpi_report_get`

Get Actuals and Targets Report · Read-only

Report actuals and targets for KPIs over a date range, aggregated to each KPI's own frequency and aggregate function, one row per KPI, breakdown item and period. Returns report rows with KPI name, period, actual, target and notes. Use simplekpi_kpi_entries_list for raw entries.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `date_from` (`string`, optional): Start of the date range (ISO 8601). Example: 2026-07-01T00:00:00.
- `date_to` (`string`, optional): End of the date range (ISO 8601). Example: 2026-07-31T00:00:00.
- `group_item_ids` (`string`, optional): Comma-separated breakdown item IDs to restrict the report to. Example: 77,78.
- `kpi_ids` (`string`, optional): Comma-separated KPI IDs to report on, for example 1234,1235. Example: 1234,1235.
- `user_ids` (`string`, optional): Comma-separated user IDs to restrict the report to. Example: 42,43.

Example input: `{}`

### `simplekpi_user_get`

Get User · Read-only

Get one user by ID. Returns the user object. Get IDs from simplekpi_users_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `user_id` (`integer`, required): ID of the user. Example: 1234.

Example input: `{"user_id":1234}`

### `simplekpi_users_list`

List Users · Read-only

List the people on the SimpleKPI account with their role, status and email. Returns user objects; pass an ID as user_id (or the email) when writing KPI entries. Users are managed in the app, not the API.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
- `rows` (`integer`, optional): Rows per page. Defaults to 500. Example: 500.

Example input: `{}`

### `simplekpi_breakdown_item_create`

Create Breakdown Item · Write

Create a breakdown item under a breakdown. Returns the item with its ID.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the item, for example a team, product or region. Example: North.
- `breakdown_id` (`integer`, optional): ID of the breakdown the item sits under; null when it combines several breakdowns. Example: 9.
- `is_archived` (`boolean`, optional): true archives the item: it keeps its history but is not offered for new entries. Example: false.
- `is_system` (`boolean`, optional): Leave false; true marks items SimpleKPI maintains itself. Example: false.
- `sort_order` (`integer`, optional): Position of the item within its breakdown. Example: 1.

Example input: `{"name":"<name>"}`

### `simplekpi_breakdown_item_update`

Update Breakdown Item · Write

Replace a breakdown item's name, breakdown, archive flag and sort order. This is a full replacement: fields left out are reset to their defaults, so read the record first and send it back changed. Returns the updated item.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`integer`, required): ID of the item to replace. Example: 1234.
- `name` (`string`, required): What this part of the breakdown is called, e.g. a person, team, product or region. Example: North.
- `breakdown_id` (`integer`, optional): Nullable. Which breakdown the item sits under. Null when the item combines more than one breakdown rather than belonging to a single one. Example: 9.
- `is_archived` (`boolean`, optional): Archived items keep their history but stop being offered for new entries. Example: false.
- `is_system` (`boolean`, optional): True for items SimpleKPI maintains itself. Leave it false when creating one; it is ignored on update, because a built-in item cannot be made ordinary through the API. Example: false.
- `sort_order` (`integer`, optional): Position of the item within its breakdown. Example: 1.

Example input: `{"item_id":1234,"name":"<name>"}`

### `simplekpi_category_kpi_create`

Create KPI in Category · Write

Create a KPI inside a category; the category comes from the path. Returns the KPI with its ID. Use simplekpi_kpi_create when the category is in the body.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `aggregate_function` (`string`, required): How values roll up over a period: SUM or AVG. Example: SUM. One of: `SUM`, `AVG`.
- `category_id` (`integer`, required): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `frequency_id` (`string`, required): How often data is entered: D daily, W weekly, M monthly, Q quarterly, Y yearly (case sensitive; see simplekpi_kpi_frequencies_list). Example: W. One of: `D`, `W`, `M`, `Q`, `Y`.
- `name` (`string`, required): What the KPI is called. Example: New Sales.
- `value_direction` (`string`, required): Which way is good: U up, D down, N neither. Example: U. One of: `U`, `D`, `N`.
- `description` (`string`, optional): Nullable. Free text shown alongside the KPI. Example: Closed-won deals per week.
- `icon_id` (`integer`, optional): ID of the icon shown with the KPI. Required in practice (0 is rejected); get IDs from simplekpi_kpi_icons_list. Example: 1.
- `is_active` (`boolean`, optional): Inactive KPIs stay on the account but are hidden from day-to-day views. Example: true.
- `sort_order` (`integer`, optional): Position of the KPI within its category. Example: 1.
- `target_default` (`number`, optional): Nullable. The target applied to new entries when none is given. Example: 100.
- `unit_id` (`integer`, optional): ID of the unit that formats the KPI's values. Send a real ID from simplekpi_kpi_units_list. Example: 123.

Example input: `{"aggregate_function":"SUM","category_id":5478,"frequency_id":"D","name":"<name>","value_direction":"U"}`

### `simplekpi_category_kpi_update`

Update KPI in Category · Write

Replace a KPI that is in the given category. This is a full replacement: fields left out are reset to their defaults, so read the record first and send it back changed. Returns the updated KPI.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `aggregate_function` (`string`, required): How values roll up over a period: SUM or AVG. Example: SUM. One of: `SUM`, `AVG`.
- `category_id` (`integer`, required): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `frequency_id` (`string`, required): How often data is entered: D daily, W weekly, M monthly, Q quarterly, Y yearly (case sensitive; see simplekpi_kpi_frequencies_list). Example: W. One of: `D`, `W`, `M`, `Q`, `Y`.
- `kpi_id` (`integer`, required): ID of the KPI to replace. Example: 1234.
- `name` (`string`, required): What the KPI is called. Example: New Sales.
- `value_direction` (`string`, required): Which way is good: U up, D down, N neither. Example: U. One of: `U`, `D`, `N`.
- `description` (`string`, optional): Nullable. Free text shown alongside the KPI. Example: Closed-won deals per week.
- `icon_id` (`integer`, optional): ID of the icon shown with the KPI. Required in practice (0 is rejected); get IDs from simplekpi_kpi_icons_list. Example: 1.
- `is_active` (`boolean`, optional): Inactive KPIs stay on the account but are hidden from day-to-day views. Example: true.
- `sort_order` (`integer`, optional): Position of the KPI within its category. Example: 1.
- `target_default` (`number`, optional): Nullable. The target applied to new entries when none is given. Example: 100.
- `unit_id` (`integer`, optional): ID of the unit that formats the KPI's values. Send a real ID from simplekpi_kpi_units_list. Example: 123.

Example input: `{"aggregate_function":"SUM","category_id":5478,"frequency_id":"D","kpi_id":1234,"name":"<name>","value_direction":"U"}`

### `simplekpi_kpi_category_create`

Create KPI Category · Write

Create a KPI category. Returns the category with its ID.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): What the category is called. Example: New Sales.
- `sort_order` (`integer`, optional): Position of the category in the list. Example: 1.

Example input: `{"name":"<name>"}`

### `simplekpi_kpi_category_update`

Update KPI Category · Write

Replace a KPI category's name and sort order. This is a full replacement: fields left out are reset to their defaults, so read the record first and send it back changed. Returns the updated category.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`integer`, required): ID of the category to replace. Example: 1234.
- `name` (`string`, required): What the category is called. Example: New Sales.
- `sort_order` (`integer`, optional): Position of the category in the list. Example: 1.

Example input: `{"category_id":1234,"name":"<name>"}`

### `simplekpi_kpi_create`

Create KPI · Write

Create a KPI with its name, frequency, value direction, aggregate function, category, icon and unit. Returns the KPI with its ID. Get icon IDs from simplekpi_kpi_icons_list and unit IDs from simplekpi_kpi_units_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `aggregate_function` (`string`, required): How values roll up over a period: SUM or AVG. Example: SUM. One of: `SUM`, `AVG`.
- `frequency_id` (`string`, required): How often data is entered: D daily, W weekly, M monthly, Q quarterly, Y yearly (case sensitive; see simplekpi_kpi_frequencies_list). Example: W. One of: `D`, `W`, `M`, `Q`, `Y`.
- `name` (`string`, required): What the KPI is called. Example: New Sales.
- `value_direction` (`string`, required): Which way is good: U up, D down, N neither. Example: U. One of: `U`, `D`, `N`.
- `category_id` (`integer`, optional): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `description` (`string`, optional): Nullable. Free text shown alongside the KPI. Example: Closed-won deals per week.
- `icon_id` (`integer`, optional): ID of the icon shown with the KPI. Required in practice (0 is rejected); get IDs from simplekpi_kpi_icons_list. Example: 1.
- `is_active` (`boolean`, optional): Inactive KPIs stay on the account but are hidden from day-to-day views. Example: true.
- `sort_order` (`integer`, optional): Position of the KPI within its category. Example: 1.
- `target_default` (`number`, optional): Nullable. The target applied to new entries when none is given. Example: 100.
- `unit_id` (`integer`, optional): ID of the unit that formats the KPI's values. Send a real ID from simplekpi_kpi_units_list. Example: 123.

Example input: `{"aggregate_function":"SUM","frequency_id":"D","name":"<name>","value_direction":"U"}`

### `simplekpi_kpi_entries_batch_upsert`

Add or Update Many KPI Entries · Write

Upsert many KPI entries in one call. Returns rows_added and rows_rejected; a batch where every row is rejected still returns 200, so check rows_rejected. Use simplekpi_kpi_entry_upsert for a single entry.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `entries` (`array`, optional): Entries to write, each shaped like a single entry: kpi_id, entry_date and actual, target or notes, plus setActual/setTarget/setNotes flags and optionally user_id or email and source_id. Example: [{"kpi_id": 1234, "entry_date": "2026-08-03T00:00:00", "actual": 42, "setActual": true}]
- `has_actuals` (`boolean`, optional): true when the batch carries actual values. Example: true.
- `has_notes` (`boolean`, optional): true when the batch carries notes. Example: false.
- `has_targets` (`boolean`, optional): true when the batch carries target values. Example: false.

Example input: `{}`

### `simplekpi_kpi_entry_update`

Update KPI Entry · Write

Update a KPI entry by ID, writing the fields chosen with setActual, setTarget and setNotes. Returns the updated entry. Get IDs from simplekpi_kpi_entries_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `entry_id` (`integer`, required): ID of the entry to update. Example: 1234.
- `actual` (`number`, optional): Nullable. The value achieved. Example: 42.
- `add_to_actual` (`boolean`, optional): Send true to add actual to the stored value instead of replacing it. Useful for feeding in events as they happen rather than recalculating a daily total. Example: false.
- `email` (`string`, optional): Nullable. Identifies the user by email address instead of user_id. Send one or the other, not both. Kept for integrations built against v1. Example: alex@example.com.
- `entry_date` (`string`, optional): Date the value is recorded against (ISO 8601). It must fit the KPI's frequency: a weekly KPI rejects a mid-week date. Example: 2026-08-03T00:00:00.
- `kpi_id` (`integer`, optional): ID of the KPI. Get IDs from simplekpi_kpis_list. Example: 1234.
- `notes` (`string`, optional): Nullable. Free text stored with the entry. Example: Two deals slipped to next week.
- `set_actual` (`boolean`, optional): Send true to write actual, false to leave whatever is already stored untouched. This is how you update a target without clearing the actual. Example: true.
- `set_notes` (`boolean`, optional): Send true to write notes, false to leave the stored text untouched. Example: false.
- `set_target` (`boolean`, optional): Send true to write target, false to leave the stored value untouched. Example: true.
- `source_id` (`integer`, optional): ID of the breakdown item (source) the value belongs to. Get IDs from simplekpi_breakdown_items_list; omit for the KPI's default. Example: 0.
- `target` (`number`, optional): Nullable. The value being aimed at. Example: 50.
- `user_id` (`integer`, optional): ID of the user the entry is recorded against (null for a KPI with no breakdown). Get IDs from simplekpi_users_list. Example: 42.

Example input: `{"entry_id":1234}`

### `simplekpi_kpi_entry_upsert`

Add or Update KPI Entry · Write

Record a value for a KPI on a date: an upsert keyed by KPI, breakdown item and date, so sending the same combination again updates it. setActual, setTarget and setNotes choose which fields are written; addToActual adds to the stored actual. Returns the entry, or a nothing-stored object when actual, target and notes were all empty. Use simplekpi_kpi_entries_batch_upsert for many entries.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `actual` (`number`, optional): Nullable. The value achieved. Example: 42.
- `add_to_actual` (`boolean`, optional): Send true to add actual to the stored value instead of replacing it. Useful for feeding in events as they happen rather than recalculating a daily total. Example: false.
- `email` (`string`, optional): Nullable. Identifies the user by email address instead of user_id. Send one or the other, not both. Kept for integrations built against v1. Example: alex@example.com.
- `entry_date` (`string`, optional): Date the value is recorded against (ISO 8601). It must fit the KPI's frequency: a weekly KPI rejects a mid-week date. Example: 2026-08-03T00:00:00.
- `kpi_id` (`integer`, optional): ID of the KPI. Get IDs from simplekpi_kpis_list. Example: 1234.
- `notes` (`string`, optional): Nullable. Free text stored with the entry. Example: Two deals slipped to next week.
- `set_actual` (`boolean`, optional): Send true to write actual, false to leave whatever is already stored untouched. This is how you update a target without clearing the actual. Example: true.
- `set_notes` (`boolean`, optional): Send true to write notes, false to leave the stored text untouched. Example: false.
- `set_target` (`boolean`, optional): Send true to write target, false to leave the stored value untouched. Example: true.
- `source_id` (`integer`, optional): ID of the breakdown item (source) the value belongs to. Get IDs from simplekpi_breakdown_items_list; omit for the KPI's default. Example: 0.
- `target` (`number`, optional): Nullable. The value being aimed at. Example: 50.
- `user_id` (`integer`, optional): ID of the user the entry is recorded against (null for a KPI with no breakdown). Get IDs from simplekpi_users_list. Example: 42.

Example input: `{}`

### `simplekpi_kpi_unit_create`

Create KPI Unit · Write

Create a unit with entry and display number formats. Returns the unit with its ID.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `display_format` (`string`, required): Number format used to show values, in the same notation, for example #,##0. Example: #,##0.
- `entry_format` (`string`, required): Number format used when values are typed in, for example #,##0.00 (digits and # are placeholders, a comma groups thousands). Example: #,##0.00.
- `name` (`string`, required): Name of the unit, for example Pounds or Percent (max 25 characters). Example: New Sales.
- `is_percentage` (`boolean`, optional): true treats values as percentages. Example: false.

Example input: `{"display_format":"<display_format>","entry_format":"<entry_format>","name":"<name>"}`

### `simplekpi_kpi_unit_update`

Update KPI Unit · Write

Replace a unit's name and formats. This is a full replacement: fields left out are reset to their defaults, so read the record first and send it back changed. Returns the updated unit.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `display_format` (`string`, required): The format used when the value is shown, in the same notation as entry_format. Example: #,##0.
- `entry_format` (`string`, required): A numeric format string used when values are typed in. Digits and # are placeholders, , groups thousands, and one decimal group is allowed — for example #,##0.00, 0.## or #.00. Example: #,##0.00.
- `name` (`string`, required): What the unit is called, e.g. Pounds or Percent. Example: Pounds.
- `unit_id` (`integer`, required): ID of the unit to replace. Example: 1234.
- `is_percentage` (`boolean`, optional): True when values are treated as percentages. Example: false.

Example input: `{"display_format":"<display_format>","entry_format":"<entry_format>","name":"<name>","unit_id":1234}`

### `simplekpi_kpi_update`

Update KPI · Write

Replace a KPI's settings. This is a full replacement: fields left out are reset to their defaults, so read the record first and send it back changed. Returns the updated KPI. Get the current values with simplekpi_kpi_get.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `aggregate_function` (`string`, required): How values roll up over a period: SUM or AVG. Example: SUM. One of: `SUM`, `AVG`.
- `frequency_id` (`string`, required): How often data is entered: D daily, W weekly, M monthly, Q quarterly, Y yearly (case sensitive; see simplekpi_kpi_frequencies_list). Example: W. One of: `D`, `W`, `M`, `Q`, `Y`.
- `kpi_id` (`integer`, required): ID of the KPI to replace. Example: 1234.
- `name` (`string`, required): What the KPI is called. Example: New Sales.
- `value_direction` (`string`, required): Which way is good: U up, D down, N neither. Example: U. One of: `U`, `D`, `N`.
- `category_id` (`integer`, optional): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `description` (`string`, optional): Nullable. Free text shown alongside the KPI. Example: Closed-won deals per week.
- `icon_id` (`integer`, optional): ID of the icon shown with the KPI. Required in practice (0 is rejected); get IDs from simplekpi_kpi_icons_list. Example: 1.
- `is_active` (`boolean`, optional): Inactive KPIs stay on the account but are hidden from day-to-day views. Example: true.
- `sort_order` (`integer`, optional): Position of the KPI within its category. Example: 1.
- `target_default` (`number`, optional): Nullable. The target applied to new entries when none is given. Example: 100.
- `unit_id` (`integer`, optional): ID of the unit that formats the KPI's values. Send a real ID from simplekpi_kpi_units_list. Example: 123.

Example input: `{"aggregate_function":"SUM","frequency_id":"D","kpi_id":1234,"name":"<name>","value_direction":"U"}`

### `simplekpi_breakdown_item_delete`

Delete Breakdown Item · Destructive

Delete a breakdown item. Returns an empty response. Get IDs from simplekpi_breakdown_items_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`integer`, required): ID of the item to delete. Example: 1234.

Example input: `{"item_id":1234}`

### `simplekpi_category_kpi_delete`

Delete KPI in Category · Destructive

Delete a KPI that is in the given category, with all its entries. This cannot be undone. Returns an empty response.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`integer`, required): ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
- `kpi_id` (`integer`, required): ID of the KPI to delete. Example: 1234.

Example input: `{"category_id":5478,"kpi_id":1234}`

### `simplekpi_kpi_category_delete`

Delete KPI Category · Destructive

Delete a KPI category. Returns an empty response. Get IDs from simplekpi_kpi_categories_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`integer`, required): ID of the category to delete. Example: 1234.

Example input: `{"category_id":1234}`

### `simplekpi_kpi_delete`

Delete KPI · Destructive

Delete a KPI and every entry recorded against it. This cannot be undone. Returns an empty response. Get IDs from simplekpi_kpis_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `kpi_id` (`integer`, required): ID of the KPI to delete. Example: 1234.

Example input: `{"kpi_id":1234}`

### `simplekpi_kpi_entry_delete`

Delete KPI Entry · Destructive

Delete a KPI entry. Returns an empty response. Get IDs from simplekpi_kpi_entries_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `entry_id` (`integer`, required): ID of the entry to delete. Example: 1234.

Example input: `{"entry_id":1234}`

### `simplekpi_kpi_unit_delete`

Delete KPI Unit · Destructive

Delete a unit that no KPI uses. Returns an empty response; a unit in use cannot be deleted.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `unit_id` (`integer`, required): ID of the unit to delete. Example: 1234.

Example input: `{"unit_id":1234}`

## Related

Other Analytics connectors ([all 177](/agentkit/connectors/?category=analytics)):

- [Google Sheets](/agentkit/connectors/googlesheets/): Scalekit connector, OAuth, 48 tools
- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [AWS Redshift](/agentkit/connectors/redshift/): Scalekit connector, Trusted identity provider, 10 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
