> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom KPI Tools

> MCP tools for querying custom KPI datasets, campaigns, and assignments

# Custom KPI Tools

Query Custom KPI data — user-defined indicators organized into **datasets**, collected through **campaigns**, and assigned to **facilities** via **assignments**. Each dataset groups related KPIs (e.g. "ESG Social Metrics"), campaigns are time-boxed data collection rounds sent to assigned facilities, and values are the submitted responses.

<Note>
  All Custom KPI tools are **read-only**. Campaign management, value submission, and invite sending are not exposed through MCP.
</Note>

## `list_custom_kpis`

List Custom KPI definitions for an organization. Returns each KPI with its parent dataset context flattened in.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description                                 |
| ----------------- | ------ | -------- | ----------- | ------------------------------------------- |
| `organization_id` | string | No       | default org | Organization UUID                           |
| `facility_id`     | string | No       | —           | Filter KPIs assigned to a specific facility |
| `dataset_id`      | string | No       | —           | Filter KPIs from a specific dataset         |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "kpi-1a2b3c4d-...",
      "dataset_id": "ds-5e6f7a8b-...",
      "dataset_name": "ESG Social Metrics",
      "dataset_description": "Core social indicators for annual reporting",
      "name": "Employee Turnover Rate",
      "description": "Percentage of employees who left during the reporting period",
      "unit": "%",
      "value_type": "percentage",
      "required": true,
      "sort_order": 0,
      "created_at": "2025-01-15T10:00:00",
      "updated_at": null
    },
    {
      "id": "kpi-9c0d1e2f-...",
      "dataset_id": "ds-5e6f7a8b-...",
      "dataset_name": "ESG Social Metrics",
      "dataset_description": "Core social indicators for annual reporting",
      "name": "Training Hours per Employee",
      "description": null,
      "unit": "hours",
      "value_type": "number",
      "required": true,
      "sort_order": 1,
      "created_at": "2025-01-15T10:00:00",
      "updated_at": "2025-03-01T14:30:00"
    }
  ],
  "total": 2
}
```

**Key response fields:**

| Field                         | Description                                                               |
| ----------------------------- | ------------------------------------------------------------------------- |
| `dataset_id` / `dataset_name` | Parent dataset context, flattened into each KPI                           |
| `value_type`                  | Expected answer type (see below)                                          |
| `unit`                        | Measurement unit (%, hours, kg, etc.) — null for text/boolean/select KPIs |
| `required`                    | Whether a response value is mandatory in campaigns                        |
| `facility_id`                 | Only present when filtering by `facility_id`                              |

<Accordion title="KPI value types">
  | Type         | Description                           |
  | ------------ | ------------------------------------- |
  | `number`     | Numeric value (integer or decimal)    |
  | `text`       | Free-form text                        |
  | `percentage` | Percentage value (0–100)              |
  | `date`       | Date (YYYY-MM-DD)                     |
  | `boolean`    | True/false                            |
  | `select`     | Single choice from predefined options |
</Accordion>

## `get_custom_kpi`

Get one Custom KPI definition with full detail — formula, unit, value type, and linked dataset. Use `list_custom_kpis` first to discover available KPI IDs.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description             |
| ----------------- | ------ | -------- | ----------- | ----------------------- |
| `dataset_id`      | string | **Yes**  | —           | UUID of the KPI dataset |
| `kpi_id`          | string | **Yes**  | —           | UUID of the KPI         |
| `organization_id` | string | No       | default org | Organization UUID       |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "kpi-1a2b3c4d-...",
  "dataset_id": "ds-5e6f7a8b-...",
  "dataset_name": "ESG Social Metrics",
  "dataset_description": "Core social indicators for annual reporting",
  "name": "Employee Satisfaction Score",
  "description": "Overall satisfaction rating from annual survey",
  "unit": null,
  "value_type": "select",
  "required": true,
  "sort_order": 2,
  "created_at": "2025-01-15T10:00:00",
  "updated_at": null
}
```

## `list_kpi_datasets`

List Custom KPI dataset containers — each dataset groups related KPIs together.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description       |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `organization_id` | string | No       | default org | Organization UUID |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "ds-5e6f7a8b-...",
      "organization_id": "a1b2c3d4-...",
      "name": "ESG Social Metrics",
      "description": "Core social indicators for annual reporting",
      "created_by": "u1a2b3c4-...",
      "updated_by": null,
      "created_at": "2025-01-15T10:00:00",
      "updated_at": null
    },
    {
      "id": "ds-3g4h5i6j-...",
      "organization_id": "a1b2c3d4-...",
      "name": "Water & Waste Tracking",
      "description": null,
      "created_by": "u1a2b3c4-...",
      "updated_by": null,
      "created_at": "2025-03-20T08:30:00",
      "updated_at": null
    }
  ],
  "total": 2
}
```

## `list_kpi_campaigns`

List data collection campaigns for a specific KPI dataset. Each campaign represents a time-boxed reporting period with a submission deadline.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description             |
| ----------------- | ------ | -------- | ----------- | ----------------------- |
| `dataset_id`      | string | **Yes**  | —           | UUID of the KPI dataset |
| `organization_id` | string | No       | default org | Organization UUID       |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "camp-1a2b3c4d-...",
      "dataset_id": "ds-5e6f7a8b-...",
      "name": "Q1 2025 ESG Collection",
      "period_start": "2025-01-01",
      "period_end": "2025-03-31",
      "deadline": "2025-04-15",
      "locked_at": null,
      "created_by": "u1a2b3c4-...",
      "updated_by": null,
      "created_at": "2025-01-10T09:00:00",
      "updated_at": null
    }
  ],
  "total": 1
}
```

**Key response fields:**

| Field                         | Description                                                         |
| ----------------------------- | ------------------------------------------------------------------- |
| `period_start` / `period_end` | The reporting period this campaign covers                           |
| `deadline`                    | Submission deadline for assigned facilities                         |
| `locked_at`                   | If set, the campaign is locked and no more submissions are accepted |

## `get_kpi_campaign_values`

Get submitted values/responses for a specific campaign — the actual data collected from facilities.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description             |
| ----------------- | ------- | -------- | ----------- | ----------------------- |
| `dataset_id`      | string  | **Yes**  | —           | UUID of the KPI dataset |
| `campaign_id`     | string  | **Yes**  | —           | UUID of the campaign    |
| `organization_id` | string  | No       | default org | Organization UUID       |
| `page`            | integer | No       | 1           | Page number             |
| `size`            | integer | No       | 50          | Results per page        |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "val-1a2b3c4d-...",
      "campaign_assignment_id": "ca-5e6f7a8b-...",
      "assignment_id": "asgn-9c0d1e2f-...",
      "kpi_id": "kpi-1a2b3c4d-...",
      "value_numeric": 12.5,
      "submitted_at": "2025-04-10T14:30:00",
      "submitter_email": "maria@acme.com",
      "submitter_user_id": "u-3g4h5i6j-...",
      "kpi_name": "Employee Turnover Rate",
      "kpi_unit": "%",
      "data_owner_email": "hr@acme.com",
      "organization_name": "ACME Spain",
      "facility_name": "Barcelona Office"
    }
  ],
  "total": 15
}
```

**Key response fields:**

| Field                   | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `value_numeric`         | The submitted numeric value (null for text/date/select KPIs) |
| `kpi_name` / `kpi_unit` | KPI context flattened into each value row                    |
| `data_owner_email`      | The person responsible for this assignment                   |
| `facility_name`         | The facility that submitted this value (null if org-level)   |
| `submitted_at`          | When the value was submitted                                 |

## `list_kpi_assignments`

List facility/user assignments for a Custom KPI dataset — which facilities and data owners are responsible for reporting.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description             |
| ----------------- | ------ | -------- | ----------- | ----------------------- |
| `dataset_id`      | string | **Yes**  | —           | UUID of the KPI dataset |
| `organization_id` | string | No       | default org | Organization UUID       |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "asgn-9c0d1e2f-...",
      "dataset_id": "ds-5e6f7a8b-...",
      "organization_id": "a1b2c3d4-...",
      "facility_id": "fac-1a2b3c4d-...",
      "data_owner_user_id": "u-3g4h5i6j-...",
      "data_owner_email": "hr@acme.com",
      "created_at": "2025-01-15T10:00:00",
      "updated_at": null
    }
  ],
  "total": 1
}
```

**Key response fields:**

| Field                | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| `facility_id`        | The assigned facility (null for org-level assignments)       |
| `data_owner_email`   | Contact email for the person responsible for data submission |
| `data_owner_user_id` | Platform user ID of the data owner (null if external)        |

**Example prompts:**

```
"List all our KPI datasets"
"What KPIs are assigned to our Barcelona factory?"
"Show me the KPI definitions in the ESG Social Metrics dataset"
"Show submitted values for the Q1 2025 ESG campaign"
"Which facilities are assigned to report on dataset ds-456?"
"What's the employee turnover rate submitted by each facility?"
```

## Workflow

1. **Discover datasets** — `list_kpi_datasets` to see available KPI dataset containers
2. **Explore definitions** — `list_custom_kpis` to see individual KPI definitions (filter by `facility_id` or `dataset_id`)
3. **Find campaigns** — `list_kpi_campaigns` to see data collection rounds and their deadlines
4. **Read submitted data** — `get_kpi_campaign_values` to retrieve the actual values submitted by facilities
5. **Check assignments** — `list_kpi_assignments` to see which facilities and data owners are responsible

## Related

<CardGroup cols={2}>
  <Card title="Elastic Data" icon="database" href="/mcp/elastic-data">
    Custom datasets with flexible schemas — a different way to track custom data
  </Card>

  <Card title="Facilities" icon="building" href="/mcp/facilities">
    Facilities that KPI datasets are assigned to
  </Card>

  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    GHG emissions data — standard environmental metrics
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/custom-kpi/overview">
    REST API endpoints for custom KPIs
  </Card>
</CardGroup>