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. On emissions, those custom columns come from every table an emission row comes from, prefixed by that source so two sources never share a key: custom_consumption_<key> (vehicle consumptions), custom_invoice_<key>, custom_waste_<key>, custom_purchase_<key>, custom_business_travel_<key>, custom_hotel_stay_<key>, custom_wastewater_<key>, custom_commuting_<key>, plus custom_vehicles_<key> and custom_facilities_<key>. They are always dimensions — an emission row is a day-by-gas slice of its source, so a number from the source (or from the record a relation points at) is never summed. When your organization links a source that has no facility of its own to a facility with a relation column (a vehicle consumption’s “Facility”, a business trip’s “Sede”), facility on emissions becomes the facility each row belongs to: its own facility when it has one, otherwise the one the relation assigns. The facility’s other columns (country, facilities__*, custom_facilities_*) follow it. The most specific source wins for each row: its own facility first, then a relation on the row’s source (a consumption’s “Facility”, which is where the vehicle was that day), then one on its vehicle, which only fills the consumptions that say nothing. So adding a relation, or leaving a new one empty, never moves a row away from the facility it had. If two facility columns on the same record point at different facilities, neither is used for that record (its vehicle’s relation, if any, still applies). Without such a relation, facility keeps its meaning.

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, with the employee’s full-time annual salary. Each remuneration is annualized over its own period (amount / its days × days of the year); one with no end date, or covering a year or more, is annual as it is. So the figure for a year does not depend on how many years the query spans. 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 revoked (INVALID_API_KEY), expired (API_KEY_EXPIRED), belongs neither to the organization in x-organization-id nor to one of its parents (API_KEY_ORG_MISMATCH), or has no owner (API_KEY_NO_OWNER). A request carrying no credentials at all answers AUTHENTICATION_REQUIRED. See Errors.

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

Organization hierarchy capability

organization_hierarchy_supported indicates whether the dataset can return recalculated holding rows when organization is the first dimension and nest_organization_by_hierarchy is enabled. Consumers should show the hierarchy control only when this capability is true. The default is false for older servers and unsupported dataset definitions.

​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

​Organization hierarchy capability

Request

Headers

Path Parameters

Query Parameters

Response

Reading the workforce schemas

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Related Endpoints

Organization hierarchy capability