Get Dataset

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": {},
  "created_by": {},
  "updated_by": {},
  "created_at": {},
  "updated_at": {},
  "kpis": {
    "id": "<string>",
    "dataset_id": "<string>",
    "name": "<string>",
    "description": {},
    "unit": {},
    "value_type": "<string>",
    "required": true,
    "sort_order": 123,
    "options": {
      "id": "<string>",
      "label": "<string>",
      "sort_order": 123
    },
    "created_at": {},
    "updated_at": {}
  }
}

GET

custom-kpi-datasets

{dataset_id}

Get Dataset

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": {},
  "created_by": {},
  "updated_by": {},
  "created_at": {},
  "updated_at": {},
  "kpis": {
    "id": "<string>",
    "dataset_id": "<string>",
    "name": "<string>",
    "description": {},
    "unit": {},
    "value_type": "<string>",
    "required": true,
    "sort_order": 123,
    "options": {
      "id": "<string>",
      "label": "<string>",
      "sort_order": 123
    },
    "created_at": {},
    "updated_at": {}
  }
}

Get Dataset

Retrieve a single custom KPI dataset by ID, including all its KPI definitions and their options.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

UUID of the datasetExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Response

Returns the dataset object with nested KPI definitions (HTTP 200).

string

Dataset UUID.

string

UUID of the organization that owns this dataset.

string

Dataset display name.

string | null

Dataset description.

string | null

UUID of the user who created the dataset.

string | null

UUID of the user who last updated the dataset.

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

array[object]

KPI definitions belonging to this dataset.

Show KPI Object

string

KPI UUID.

string

Parent dataset UUID.

string

KPI display name.

string | null

KPI description.

string | null

Measurement unit (e.g. m³, kWh, %).

string

Data type: number, text, percentage, date, boolean, or select.

boolean

Whether a response value is mandatory.

integer

Display order within the dataset.

array[object]

Available choices for select-type KPIs. Empty array for other types.

Show Option Object

string

Option UUID.

string

Display label for this option.

integer

Display order within the options list.

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

Example

curl -X GET "https://api.dcycle.io/v1/custom-kpi-datasets/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

dataset_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}",
    headers=headers,
)

dataset = response.json()
print(f"{dataset['name']} — {len(dataset['kpis'])} KPIs")
for kpi in dataset["kpis"]:
    print(f"  [{kpi['value_type']}] {kpi['name']}")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

const id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

axios.get(`https://api.dcycle.io/v1/custom-kpi-datasets/${id}`, { headers })
  .then(response => {
    const ds = response.data;
    console.log(`${ds.name}: ${ds.kpis.length} KPIs`);
  });

Successful Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": "Water Usage Survey",
  "description": "Monthly water consumption across facilities",
  "created_by": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "updated_by": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": null,
  "kpis": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Total water consumed",
      "description": null,
      "unit": "m³",
      "value_type": "number",
      "required": true,
      "sort_order": 0,
      "options": [],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": null
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Water source",
      "description": null,
      "unit": null,
      "value_type": "select",
      "required": true,
      "sort_order": 1,
      "options": [
        {"id": "e5f6a7b8-c9d0-1234-efab-345678901234", "label": "Municipal supply", "sort_order": 0},
        {"id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "label": "Well water", "sort_order": 1},
        {"id": "a7b8c9d0-e1f2-3456-abcd-567890123456", "label": "Rainwater harvesting", "sort_order": 2}
      ],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": null
    }
  ]
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: Dataset not found

{
  "detail": "Dataset not found"
}

Update Dataset

Modify dataset name or description

Delete Dataset

Remove an unused dataset

​Get Dataset

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Update Dataset

Delete Dataset

Get Dataset

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints