Custom KPI Tools

Query and submit 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.

`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:

{
  "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`

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

`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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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?"

`submit_kpi_response`

Submit values for a Custom KPI campaign. Each entry targets a specific KPI and provides the appropriate value type (numeric, text, date, or select option). Parameters:

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the KPI dataset
`campaign_id`	string	Yes	—	UUID of the campaign to submit values for
`values`	object[]	Yes	—	List of value entries (see below)
`facility_id`	string	No	—	UUID of the facility (if KPI is facility-scoped)
`organization_id`	string	No	default org	Organization UUID

Value entry fields:

Field	Type	Description
`kpi_id`	string	Required. UUID of the KPI
`value_numeric`	number	For numeric KPIs (e.g. 42.5)
`value_text`	string	For text KPIs
`value_date`	string	For date KPIs (`YYYY-MM-DD`)
`option_id`	string	For select-type KPIs — UUID of the chosen option

Each entry must include kpi_id and exactly one value field matching the KPI’s type. Use get_kpi_campaign_values to see which KPIs are expected, and list_kpi_assignments to find the correct facility_id.

Example prompts:

"Submit a value of 12.5% for the employee turnover KPI in the Q1 campaign"
"Report Barcelona office water consumption as 1250 cubic meters for dataset ds-456"
"Fill in the ESG social metrics campaign with the latest facility data"

Values are submitted permanently. Double-check KPI IDs and values before submitting — use get_kpi_campaign_values to verify what’s expected.

Workflow

Discover datasets — list_kpi_datasets to see available KPI dataset containers
Explore definitions — list_custom_kpis to see individual KPI definitions (filter by facility_id or dataset_id)
Find campaigns — list_kpi_campaigns to see data collection rounds and their deadlines
Read submitted data — get_kpi_campaign_values to retrieve the actual values submitted by facilities
Check assignments — list_kpi_assignments to see which facilities and data owners are responsible
Submit values — submit_kpi_response to submit KPI values for a campaign

Elastic Data

Custom datasets with flexible schemas — a different way to track custom data

Facilities

Facilities that KPI datasets are assigned to

Emissions

GHG emissions data — standard environmental metrics

API Reference

REST API endpoints for custom KPIs

​Custom KPI Tools

​list_custom_kpis

​get_custom_kpi

​list_kpi_datasets

​list_kpi_campaigns

​get_kpi_campaign_values

​list_kpi_assignments

​submit_kpi_response

​Workflow

​Related

Elastic Data

Facilities

Emissions

API Reference

Custom KPI Tools

`list_custom_kpis`

`get_custom_kpi`

`list_kpi_datasets`

`list_kpi_campaigns`

`get_kpi_campaign_values`

`list_kpi_assignments`

`submit_kpi_response`

Workflow

Related