Get Dataset Schema

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

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

import requests

url = "https://api.dcycle.io/v1/datasets/{key}/schema"

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

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

print(response.text)

{
  "key": "<string>",
  "label_key": "<string>",
  "kind": "<string>",
  "dimensions": {
    "key": "<string>",
    "label_key": "<string>",
    "field_type": "<string>",
    "group": "<string>",
    "i18n_namespace": {},
    "relation_label": {},
    "via": {}
  },
  "metrics": {
    "key": "<string>",
    "label_key": "<string>",
    "agg": "<string>",
    "decimals": 123,
    "suffix": {},
    "grouping_hint_key": {},
    "row_level": true
  },
  "default_metrics": {},
  "window_required": true,
  "time_axis_default": {},
  "data_version": {}
}

GET

datasets

{key}

schema

Get Dataset Schema

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

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

import requests

url = "https://api.dcycle.io/v1/datasets/{key}/schema"

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

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

print(response.text)

{
  "key": "<string>",
  "label_key": "<string>",
  "kind": "<string>",
  "dimensions": {
    "key": "<string>",
    "label_key": "<string>",
    "field_type": "<string>",
    "group": "<string>",
    "i18n_namespace": {},
    "relation_label": {},
    "via": {}
  },
  "metrics": {
    "key": "<string>",
    "label_key": "<string>",
    "agg": "<string>",
    "decimals": 123,
    "suffix": {},
    "grouping_hint_key": {},
    "row_level": true
  },
  "default_metrics": {},
  "window_required": true,
  "time_axis_default": {},
  "data_version": {}
}

Return what a dataset can be grouped by and what it can measure. Query datasets accepts only the dimension and metric keys listed here, so this is the contract to build a query against rather than guessing field names. The same native key can return different dimensions for different organizations: the schema is extended with the custom columns your organization defined on that entity. Fetch it per organization; do not cache one organization’s schema and reuse it for another.

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

Dataset key from List Available Datasets — a catalogue key, or elastic:<uuid> for a custom datasetExample: own_workforce_remuneration

Query Parameters

string

Narrow the dataset to a reporting taxonomy. It only affects datasets with framework-specific dimensions — notably emissions — and is a no-op elsewhere.

Response

string

Echo of the dataset key

string

i18n key for native datasets; the user’s literal name for custom ones

string

kpi, activity, master, custom or custom_kpi

array[object]

Show dimension

string

What to send in the query’s dimensions

string

i18n key for the dimension name

string

string, number, date, …

string

Which entity the dimension comes from, for grouping in a picker

string | null

When set, the dimension’s values are translation keys in this namespace — gender and accident_context are the workforce examples. Translate the values, not just the label.

string | null

Set when the dimension is borrowed through a relation column

string | null

The relation column it was borrowed through. Advisory — the query accepts every listed dimension regardless.

array[object]

Show metric

string

What to send in the query’s metrics

string

i18n key for the metric name

string

How the value is aggregated across rows.Read it together with row_level. When row_level is false the metric’s expression is already an aggregate — a count, a ratio, a wage gap — and agg carries its default sum without being applied. That is why remuneration_avg and wage_gap both report "agg": "sum" in the example below: the field describes the engine’s aggregation step, not the metric’s meaning, and for these two there is no such step.

integer

Suggested precision for display

string | null

Unit to render after the value — h, %, t CO₂e

string | null

Dimension the metric is most meaningful grouped by

boolean

false when the metric is already an aggregate — a count, a ratio, a gap. A row-mode formula over such a metric is rejected with 400.

array[string]

Metrics to preselect when nothing is chosen

boolean

true for native KPI and activity datasets: the query’s start/end window is mandatory and drives proration. false for master and custom datasets, where the window is optional or ignored.

string | null

The dimension that seeds the period axis

integer | null

Custom datasets only: incremented on every write, so it works as a cache key. Null for native datasets.

Every dataset with a date column also exposes a synthetic period dimension that is not part of its stored fields. It is how you group by month, quarter or year.

Reading the workforce schemas

own_workforce_remuneration is the one worth knowing in detail. Its time axis is annual — one row per employee per fiscal year — and its wage_gap metric has three traps worth repeating from Query datasets:

it is an FTE-weighted mean, not a simple average of salaries;
the sign is positive when men earn more, since it is computed as (avg_M − avg_F) / avg_M × 100;
it returns null, not 0, for any group that lacks at least one man and one woman. Null is “not computable here”, and it is not summable or averageable across groups — ask the server for subtotals instead of aggregating the numbers yourself.

It also carries fewer dimensions than own_workforce_contracts: organization, country, nationality, gender, job category, age and period, with no contract type, workday type, disability or labour-agreement split.

Example

curl -X GET "https://api.dcycle.io/v1/datasets/own_workforce_remuneration/schema" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import os

import requests

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

schema = requests.get(
    "https://api.dcycle.io/v1/datasets/own_workforce_remuneration/schema",
    headers=headers,
).json()

print("group by:", [d["key"] for d in schema["dimensions"]])
print("measure:", [m["key"] for m in schema["metrics"]])

const axios = require('axios');

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

axios.get('https://api.dcycle.io/v1/datasets/own_workforce_remuneration/schema', { headers })
  .then(({ data }) => {
    console.log('group by:', data.dimensions.map(d => d.key));
    console.log('measure:', data.metrics.map(m => m.key));
  })
  .catch(error => console.error(error));

Successful Response

{
  "key": "own_workforce_remuneration",
  "label_key": "datasets.own_workforce_remuneration.label",
  "kind": "activity",
  "dimensions": [
    { "key": "organization", "label_key": "datasets.dim.organization", "field_type": "string", "group": "own_workforce_remuneration", "i18n_namespace": null },
    { "key": "gender", "label_key": "datasets.dim.gender", "field_type": "string", "group": "own_workforce_remuneration", "i18n_namespace": "customDashboard.pivotTable.values.gender" },
    { "key": "job_category", "label_key": "datasets.dim.job_category", "field_type": "string", "group": "own_workforce_remuneration", "i18n_namespace": null },
    { "key": "age", "label_key": "datasets.dim.age", "field_type": "number", "group": "own_workforce_remuneration", "i18n_namespace": null },
    { "key": "period", "label_key": "datasets.dim.period", "field_type": "date", "group": "own_workforce_remuneration", "i18n_namespace": null }
  ],
  "metrics": [
    { "key": "remuneration_avg", "label_key": "datasets.own_workforce_remuneration.metric.remuneration_avg", "agg": "sum", "decimals": 2, "suffix": null, "row_level": false },
    { "key": "wage_gap", "label_key": "datasets.own_workforce_remuneration.metric.wage_gap", "agg": "sum", "decimals": 2, "suffix": "%", "row_level": false }
  ],
  "default_metrics": ["remuneration_avg"],
  "window_required": true,
  "time_axis_default": "year",
  "data_version": null
}

Common Errors

401 Unauthorized

Cause: the key is invalid, or it does not belong to the organization in x-organization-id — the two are looked up as a pair. A request carrying no credentials at all answers AUTH_REQUIRED instead.

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

404 Not Found

Cause: unknown key, or a custom dataset belonging to another organization.

{
  "detail": "Unknown dataset 'own_workforce_salaries'."
}

List available datasets

Where the key comes from

Query datasets

Run the aggregation

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Reading the workforce schemas

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Related Endpoints

List available datasets

Query datasets

Request

Headers

Path Parameters

Query Parameters

Response

Reading the workforce schemas

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Related Endpoints