Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to SimpleKPI

Scalekit connector
Open markdown

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.

Tools
38
What they doRead · write · destructive
19 · 13 · 619 read13 write6 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .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.

  4. Authorize a user and make your first call

    quickstart.mts
    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)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their SimpleKPI credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • simplekpi_breakdown_item_getGet one breakdown item by ID.Read-only

    Get Breakdown Item

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

    Inputs

    item_idintegerrequired
    ID of the breakdown item. Example: 1234.
  • simplekpi_breakdown_items_listList the breakdown items (the people, teams, products or regions a KPI is split by).Read-only

    List Breakdown Items

    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.

    Inputs

    pageinteger
    Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
    rowsinteger
    Rows per page. Defaults to 500. Example: 500.
  • simplekpi_category_kpi_getGet one KPI from a category.Read-only

    Get KPI in Category

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

    Inputs

    category_idintegerrequired
    ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
    kpi_idintegerrequired
    ID of the KPI. Example: 1234.
  • simplekpi_category_kpis_listList the KPIs in one category, a page at a time.Read-only

    List KPIs in Category

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

    Inputs

    category_idintegerrequired
    ID of the KPI category. Get IDs from simplekpi_kpi_categories_list. Example: 5478.
    pageinteger
    Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
    rowsinteger
    Rows per page. Defaults to 500. Example: 500.
  • simplekpi_kpi_categories_listList the KPI categories (groups of KPIs).Read-only

    List KPI Categories

    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.

    Inputs

    pageinteger
    Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
    rowsinteger
    Rows per page. Defaults to 500. Example: 500.
  • simplekpi_kpi_category_getGet one KPI category by ID.Read-only

    Get KPI Category

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

    Inputs

    category_idintegerrequired
    ID of the category. Example: 1234.
  • simplekpi_kpi_entries_listList raw KPI entries (actuals, targets, notes per date), filtered by KPI, user, breakdown item and date range, a page at a time.Read-only

    List KPI Entries

    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.

    Inputs

    date_fromstring
    Earliest entry date to include. Example: 2026-07-01T00:00:00.
    date_tostring
    Latest entry date to include. Example: 2026-07-31T00:00:00.
    kpi_idinteger
    Only entries for this KPI. Example: 1234.
    pageinteger
    Page to return, counting from 1. Lists return a plain array; keep paging until a page has fewer than rows items. Example: 1.
    rowsinteger
    Rows per page. Defaults to 500. Example: 500.
    source_idinteger
    Only entries for this breakdown source. Example: 0.
    user_idinteger
    Only entries recorded against this user. Example: 42.
  • simplekpi_kpi_entry_getGet one KPI entry by ID.Read-only

    Get KPI Entry

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

    Inputs

    entry_idintegerrequired
    ID of the entry. Example: 1234.