Request API Token

Hit our login endpoint and it will return you a session token to use in an Authroization header for requests.

POST https://dashboard.prd.cloud.reveliolabs.com/login
{
  username: [you@company.com],
  password: [password]
}

Example request:

            query_url = "https://dashboard.prd.cloud.reveliolabs.com/query"
            auth_url = "https://dashboard.prd.cloud.reveliolabs.com/login"
            
            auth_body = {
                'username': "[you@company.com]",
                'password': "[password]",
            }
            
            resp = requests.post(auth_url, json=auth_body)
            
            if resp.status_code != http.HTTPStatus.CREATED:
                raise RuntimeError('unable to get session token')
            
            response_dict = json.loads(resp.text)
            
            token = response_dict.get('session_token')
            print(token)
            
            headers = {'Authorization': f'Bearer {token}'}
            body = {"query": req_body, "variables": input_str}
            resp = requests.post(query_url, json=body, headers=headers)
            

Use API Keys

Request your Revelio Labs administrator for a API Key that you can use to authorize requests. You can pass this as an X-API-Key header.

Example request:

query_url = "https://dashboard.prd.cloud.reveliolabs.com/query"
            api_key = 'YOUR_API_KEY'
            
            headers = {'X-API-Key': f'{api_key}'}
            req_body = 'REDACTED'
            input_str = 'REDACTED'
            
            body = {"query": req_body, "variables": input_str}
            resp = requests.post(query_url, json=body, headers=headers)
            

Role, skill, industry (RICS) and geography values are organised into taxonomies — versioned trees you fetch with the taxonomy query and then feed into composition_v3. This section explains how the pieces fit together, and in particular how the generic role/skill levels relate to the explicit k-named fields that the deprecated selectionList query used to expose.

The three steps

1. Discover a taxonomy. taxonomyList returns the available taxonomies (id, name, version) for a taxonomy_type; taxonomyVersions / taxonomyLatestVersion list versions. (roleTaxonomies is the role-specific equivalent.) The id you get back is the taxonomy_id.
2. Fetch the tree. taxonomy(req: { taxonomy_type, taxonomy_id, taxonomy_version, levels }) returns levels (level metadata) and nodes (the tree). Each node has an id, name, count, optional titles, and children.
3. Use it in composition_v3. Pass the taxonomy_id as role_taxonomy / skill_taxonomy, filter the population with node ids at a generic level (role_level_*, skills_level_*), and pick the breakdown granularity with *_breakdown_level.

Levels: generic index vs. concrete k

The levels array is the key to the whole model. Each entry has:

• id — the generic level index. This is what you pass to composition_v3: filters.role_level_<id> / filters.skills_level_<id>, and the breakdown tier EntKind.ROLE_LVL_<id> / SKILL_LVL_<id>.
• tag — the concrete k-granularity of this level (e.g. role_k150, skill_k1500, rics_k400). These values are specific to the taxonomy you queried; the deprecated selectionList exposed the default taxonomy's granularities as fixed k-named fields.
• label — a human-readable label.

Previously you picked granularity by choosing a k-named field on selectionList. Now it is data returned by the query: each levels entry's tag is the concrete k for the taxonomy you queried, and its id is the generic level you pass to composition_v3 (e.g. id 3 → role_level_3 filter / ROLE_LVL_3 breakdown). Because the mapping is per-taxonomy, read it from levels rather than assuming fixed k-values.

Dimension	taxonomy_type	example levels[].tag	levels[].id → composition_v3
Role	ROLE	role_k150	3 → role_level_3 / ROLE_LVL_3
Skill	SKILL	skill_k1500	5 → skills_level_5 / SKILL_LVL_5
Industry	RICS	rics_k400	3 → rics_k400 / RICS_K400
Geography	GEOGRAPHY	country	2 → country filter / EntKind.COUNTRY

A taxonomy's levels are a subset of the tiers composition_v3 accepts. A taxonomy lists only the granularities it defines, and its tag values are specific to it — a different taxonomy_id (including the default one selectionList drew from) can expose different k-levels. composition_v3 itself always accepts the full fixed set of tiers via EntKind and the rics_k* / role_level_* / skills_level_* filters: RICS accepts RICS_K10/K50/K400 and geography accepts STATE, for instance, even though the example taxonomies below don't list rics_k50 or state.

Worked examples — one per taxonomy_type

Each is a taxonomy(req: …) call; the levels it returns are shown below (the nodes tree is omitted for brevity). The taxonomy_id comes from taxonomyList.

Role — taxonomy(req: { taxonomy_type: "ROLE", taxonomy_id: 0 }). Job category down to fine-grained roles. The adaptive tree returns the odd levels; a full taxonomy also fills the even ones (role_k50, role_k500, role_k5000).

"levels": [
  { "id": 1, "tag": "role_k7",     "label": "Job Category" },
  { "id": 3, "tag": "role_k150",   "label": "K150" },
  { "id": 5, "tag": "role_k1500",  "label": "K1500" },
  { "id": 7, "tag": "role_k15000", "label": "K15000" }
]

Skill — taxonomy(req: { taxonomy_type: "SKILL", taxonomy_id: 6 }). Broad clusters down to fine-grained skills. The tags shown are from an adaptive skill taxonomy; the default taxonomy selectionList drew from used different granularities (skill_k25…skill_k3000).

"levels": [
  { "id": 3, "tag": "skill_k150",   "label": "Skill K150" },
  { "id": 5, "tag": "skill_k1500",  "label": "Skill K1500" },
  { "id": 6, "tag": "skill_k5000",  "label": "Skill K5000" },
  { "id": 7, "tag": "skill_k15000", "label": "Skill K15000" }
]

RICS (industry) — taxonomy(req: { taxonomy_type: "RICS", taxonomy_id: 0 }). Coarse sectors down to individual companies. This taxonomy exposes rics_k10, rics_k400 and company; composition_v3 additionally accepts the intermediate rics_k50 tier (RICS_K50).

"levels": [
  { "id": 1, "tag": "rics_k10",  "label": "k10" },
  { "id": 3, "tag": "rics_k400", "label": "k400" },
  { "id": 4, "tag": "company",   "label": "Company" }
]

Geography — taxonomy(req: { taxonomy_type: "GEOGRAPHY", taxonomy_id: 0 }). This taxonomy is region → country → metro area → city. It does not include state; the administrative hierarchy with states is a separate taxonomy. (composition_v3 still accepts STATE as a geo_breakdown_level, sourced from that administrative geography.)

"levels": [
  { "id": 1, "tag": "region",  "label": "Region" },
  { "id": 2, "tag": "country", "label": "Country" },
  { "id": 3, "tag": "msa",     "label": "Metro Area" },
  { "id": 4, "tag": "city",    "label": "City" }
]

Putting it together in composition_v3

Say you fetched the role tree above (role_taxonomy id 0) and want Workday's headcount within the Sales and Marketing job category, broken down into its k150 sub-roles:

{
  "entities": [{ "EntType": "COMPANY", "EntID": 1116644 }],
  "filters": {
    "start_date": "2024-01",
    "end_date": "2024-12",
    "role_level_1": [8]
  },
  "role_taxonomy": 0,
  "skill_taxonomy": 6,
  "breakdown_options": { "role_breakdown_level": "ROLE_LVL_3" }
}

• role_level_1: [8] filters to node 8 (“Sales and Marketing”), which sits at level 1 (role_k7) in the tree.
• role_breakdown_level: "ROLE_LVL_3" returns the breakdown one tier finer, at level 3 (role_k150).
• role_taxonomy: 0 ties both the filter level and the breakdown level to that specific role taxonomy.

Skill works identically with skill_taxonomy, skills_level_* and SKILL_LVL_*; RICS with rics_k10/50/400 and RICS_K10/50/400; geography with region/country/msa/city and the matching EntKind. The static demographic dimensions (gender, ethnicity, highestDegree, seniority) are plain {id, name} lookups — use their ids in filters and breakdown_options.