Clarity AI
App · 25 actions
Sustainability data for investors: ESG risk scores, carbon footprint, SFDR, EU Taxonomy, controversies and exposures for portfolios, funds and companies.
Actions
| Action | What it does |
|---|---|
| Create portfolio | Create a portfolio from holdings. |
| Delete portfolio | Delete a portfolio from your Clarity AI account. |
| Get company EU Taxonomy alignment | Get how much of a company's business is EU Taxonomy eligible and aligned, for one environmental objective, by its ISIN. |
| Get data download | Read the rows of a download Clarity AI has prepared, waiting until it is ready if you like. |
| Get fund carbon footprint | Get a fund's weighted average carbon intensity and the emissions financed by an amount invested in it, with peer percentiles. |
| Get fund climate scores | Get a fund's emissions (scope 1, 2 and 3, and the total), its companies' reduction commitments, and percentiles against peer funds. |
| Get fund ESG risk scores | Get a fund's ESG Risk score, its Environmental, Social and Governance scores, coverage and peer group, or particular scores by id. |
| Get fund EU Taxonomy alignment | Get how much of a fund is EU Taxonomy eligible and aligned, for one environmental objective, by turnover, CapEx or OpEx. |
| Get fund exposures | Check whether a fund is exposed to business activities such as coal mining or tobacco, and how much of it is. |
| Get fund holdings | Get the companies a fund holds, through any funds inside it, largest first, with their PermIDs for 'Request company data download'. |
| Get portfolio | Get a portfolio's holdings and status. |
| Get portfolio carbon footprint | Get a portfolio's financed emissions and weighted average carbon intensity (scope 1 and 2), with how much of it is covered. |
| Get portfolio climate scores | Get a portfolio's emissions (scope 1, 2 and 3, and the total) and its companies' emission reduction commitments. |
| Get portfolio ESG risk scores | Get a portfolio's ESG Risk score, its Environmental, Social and Governance scores and coverage, or particular scores by id. |
| Get portfolio EU Taxonomy alignment | Get how much of a portfolio is EU Taxonomy eligible and aligned, for one environmental objective, by turnover, CapEx or OpEx. |
| Get portfolio exposures | Check whether a portfolio is exposed to business activities such as coal mining or tobacco, and how much of it is. |
| Get portfolio impact highlights | Get a portfolio's environmental and social impact, such as water withdrawn or emissions, also put in everyday terms. |
| Get portfolio SFDR indicators | Get a portfolio's SFDR principal adverse impact (PAI) indicators, such as carbon footprint and GHG intensity, with coverage. |
| Get top emitting sectors | Get the five industry sectors that contribute most to a portfolio's financed emissions (scope 1 and 2). |
| Get top holdings' ESG risk scores | Get the ten largest companies in a portfolio by weight, with each one's ESG Risk and pillar scores. |
| List portfolios | List the portfolios in your Clarity AI account, with their ids. |
| Look up company IDs | Ask Clarity AI which companies issue a list of securities (ISINs or CUSIPs), or match LEIs to PermIDs. |
| Request company data download | Ask Clarity AI for one data set (ESG risk, controversies, carbon footprint, net zero, SFDR and more) for a list of companies by PermID. |
| Request security data download | Ask Clarity AI for one data set (ESG risk, UN Global Compact, carbon footprint, SFDR and more) for a list of shares, bonds or funds. |
| Update portfolio | Replace a portfolio's holdings, and rename it if you like. |
Create portfolio
Create a portfolio from holdings. Clarity AI takes a few seconds to process it: use 'Get portfolio' with 'Wait until ready' before reading its data.
Inputs
- Name
nametextRequired - The portfolio's name, unique in your Clarity AI account.
- Holdings
holdingslistRequired - One holding per row: the security's ISIN (or CUSIP, LEI or PermID) and its weight, such as US0378331005, 60. Percentages must add up to 100. A list of records with id and weight from an earlier step works too. A portfolio needs at least two companies.
- Weights are
weightingtext - Whether each holding's weight is a percentage of the portfolio or an amount of money. Defaults to percentages.One of:
PERCENTAGE(Percentages of the portfolio),AMOUNT(Amounts of money). Default:PERCENTAGE. - Total value
total_valuenumber - What the whole portfolio is worth, used for financed emissions. Defaults to 1,000,000 when weights are percentages.At least 0.01.
- Currency
currencytext - The three-letter currency code of the total and of amounts, such as USD or EUR. Defaults to USD.
- LEI and PermID holdings are
security_typetext - Holdings given by LEI or PermID name a company, not a security: say whether it is held as shares or bonds. Defaults to equity.One of:
EQUITY(Equity (shares)),FIXED_INCOME(Fixed income (bonds)). Default:EQUITY.
Outputs
currencytext- The total's currency, such as USD
holding_countnumber- How many holdings it has
holdingslist- The holdings
idtext- The portfolio's id
is_readytrue/false- True once the portfolio is CREATED and its data can be read
nametext- The portfolio's name
rejection_causetext- Why Clarity AI rejected it (empty unless REJECTED)
statustext- DRAFT or UPDATING while Clarity AI processes it, then CREATED (ready) or REJECTED
total_valuenumber- The portfolio's total value
weightingtext- PERCENTAGE or AMOUNT
Example output
{
"currency": "USD",
"holding_count": 2,
"holdings": [
{
"id": "US0378331005",
"id_type": "ISIN",
"percentage": 60,
"security_type": ""
},
{
"id": "US5949181045",
"id_type": "ISIN",
"percentage": 40,
"security_type": ""
}
],
"id": "650edc5ff188042e8fc2196b",
"is_ready": false,
"name": "Global equity sleeve",
"rejection_cause": "",
"status": "DRAFT",
"total_value": 1000000,
"weighting": "PERCENTAGE"
}Delete portfolio
Delete a portfolio from your Clarity AI account.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Outputs
deletedtrue/false- Always true
portfolio_idtext- The deleted portfolio's id
Example output
{
"deleted": true,
"portfolio_id": "650edc5ff188042e8fc2196b"
}Get company EU Taxonomy alignment
Get how much of a company's business is EU Taxonomy eligible and aligned, for one environmental objective, by its ISIN.
Inputs
- Company ISIN
company_isintextRequired - The ISIN of one of the company's shares or bonds, such as US0378331005.
- Environmental objective
objectivetext - Which EU Taxonomy objective to report on. Defaults to climate change mitigation.One of:
mitigation(Climate change mitigation),adaptation(Climate change adaptation),water(Water and marine resources),circular(Circular economy),pollution(Pollution prevention and control),biodiversity(Biodiversity and ecosystems),aggregation(All objectives together). Default:mitigation. - Measured by
kpitext - Turnover, CapEx or OpEx. Defaults to turnover.One of:
turnover(Turnover (revenue)),capex(Capital expenditure (CapEx)),opex(Operating expenditure (OpEx)). Default:turnover. - Activities
metric_idslist - EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
Outputs
clarity_idtext- Clarity AI's own id for the company
companytext- The company's name
countnumber- How many activities came back
isintext- The ISIN asked about
metricslist- Each activity asked for, or the total
objectivetext- The EU Taxonomy objective
Example output
{
"clarity_id": "a1b2c3d4e5",
"company": "Apple Inc",
"count": 1,
"isin": "US0378331005",
"metrics": [
{
"aligned": 8.4,
"eligible": 32.5,
"id": "TOTAL",
"metadata": "",
"not_aligned": 85.3,
"not_eligible": 61.2,
"steps": {
"step1": {
"eligible": {
"metadata": "NONE",
"units": "%",
"value": 32.5
},
"notEligible": {
"metadata": "NONE",
"units": "%",
"value": 61.2
}
},
"step5": {
"aligned": {
"metadata": "NONE",
"units": "%",
"value": 8.4
},
"notAligned": {
"metadata": "NONE",
"units": "%",
"value": 85.3
}
}
},
"units": "",
"value": null
}
],
"objective": "mitigation"
}Get data download
Read the rows of a download Clarity AI has prepared, waiting until it is ready if you like. Each row is a security or company with a column per score or metric.
Inputs
- Job ID
job_idtextRequired - The job id a 'Request security data download', 'Request company data download' or 'Look up company IDs' step returned.
- Wait until ready
wait_until_readytrue/false - Wait while Clarity AI prepares the file. Off returns at once, with status RUNNING and no rows if it isn't ready.Default:
true. - Most rows
max_rowsnumber - The most rows to return, 1 to 10,000. Defaults to 1,000.From 1 to 10000.
Outputs
columnslist- The file's columns, in order
is_readytrue/false- True once the file was read
job_idtext- The download's job id
returned_countnumber- How many rows came back
row_countnumber- How many rows the file has
rowslist- The file's rows, up to 'Most rows'
statustext- RUNNING, SUCCESS or ERROR, as Clarity AI reports the job
truncatedtrue/false- True when the file has more rows than came back
Example output
{
"columns": [
"ISIN",
"ESG",
"ENVIRONMENTAL",
"SOCIAL",
"GOVERNANCE"
],
"is_ready": true,
"job_id": "644381ce-93c5-4a6b-b0a7-32a5a62d4acb",
"returned_count": 2,
"row_count": 2,
"rows": [
{
"ENVIRONMENTAL": 58,
"ESG": 62,
"GOVERNANCE": 71,
"ISIN": "US0378331005",
"SOCIAL": 66
},
{
"ENVIRONMENTAL": 70,
"ESG": 74,
"GOVERNANCE": 80,
"ISIN": "US5949181045",
"SOCIAL": 72
}
],
"status": "SUCCESS",
"truncated": false
}Get fund carbon footprint
Get a fund's weighted average carbon intensity and the emissions financed by an amount invested in it, with peer percentiles.
Inputs
- Fund ISIN or CUSIP
fund_idtextRequired - The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
- Amount invested
invested_amountnumber - The investment to work financed emissions out for. Defaults to 1,000,000.At least 1.
- Currency
currencytext - The amount's three-letter currency code, such as USD or EUR. Defaults to USD.
Outputs
allocation_datetext- When the fund's holdings were last read
carbon_intensitynumber- Weighted average carbon intensity, scope 1 and 2
countnumber- How many metrics came back
financed_emissionsnumber- Financed emissions, scope 1 and 2
fund_idtext- The fund's ISIN or CUSIP
id_typetext- ISIN or CUSIP
metricslist- The climate metrics
nametext- The fund's name
peer_group_idtext- The fund's peer group in Clarity AI
total_organizationsnumber- Companies in the fund
Example output
{
"allocation_date": "2026-09-30",
"carbon_intensity": 96.1,
"count": 2,
"financed_emissions": 52.3,
"fund_id": "IE00B4L5Y983",
"id_type": "ISIN",
"metrics": [
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "TOTAL_FINANCED_EMISSIONS_SCOPE_1_2",
"metadata": "NONE",
"name": "Financed emissions (scope 1 and 2)",
"peers_percentile": 57,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 52.3
},
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "WEIGHTED_AVERAGE_CARBON_INTENSITY_SCOPE_1_2",
"metadata": "NONE",
"name": "Weighted average carbon intensity (scope 1 and 2)",
"peers_percentile": 61,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e / USD M revenue",
"value": 96.1
}
],
"name": "iShares Core MSCI World UCITS ETF",
"peer_group_id": "5689",
"total_organizations": 1432
}Get fund climate scores
Get a fund's emissions (scope 1, 2 and 3, and the total), its companies' reduction commitments, and percentiles against peer funds.
Inputs
- Fund ISIN or CUSIP
fund_idtextRequired - The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
Outputs
allocation_datetext- When the fund's holdings were last read
countnumber- How many metrics came back
fund_idtext- The fund's ISIN or CUSIP
id_typetext- ISIN or CUSIP
metricslist- The climate metrics
nametext- The fund's name
peer_group_idtext- The fund's peer group in Clarity AI
total_organizationsnumber- Companies in the fund
Example output
{
"allocation_date": "2026-09-30",
"count": 2,
"fund_id": "IE00B4L5Y983",
"id_type": "ISIN",
"metrics": [
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "CO2DIRECTSCOPE1",
"metadata": "NONE",
"name": "Scope 1 CO2e emissions (direct)",
"peers_percentile": 57,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 87.0
},
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "CO2INDIRECTSCOPE2",
"metadata": "NONE",
"name": "Scope 2 CO2e emissions (indirect)",
"peers_percentile": 44,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 21.0
}
],
"name": "iShares Core MSCI World UCITS ETF",
"peer_group_id": "5689",
"total_organizations": 1432
}Get fund ESG risk scores
Get a fund's ESG Risk score, its Environmental, Social and Governance scores, coverage and peer group, or particular scores by id.
Inputs
- Fund ISIN or CUSIP
fund_idtextRequired - The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
- Score IDs
score_idslist - Particular ESG Risk scores of the fund, such as ENVIRONMENTAL, SOCIAL, GOVERNANCE or a category or metric id from Clarity AI's data dictionary. Leave empty for the total and the three pillars.
Outputs
allocation_datetext- When the fund's holdings were last read
coverage_weightnumber- Share of the fund with ESG data, as a percentage
environmental_scorenumber- The Environmental pillar score, 0 to 100
fund_idtext- The fund's ISIN or CUSIP
governance_scorenumber- The Governance pillar score, 0 to 100
id_typetext- ISIN or CUSIP
nametext- The fund's name (empty when Clarity AI doesn't say)
peer_group_idtext- The fund's peer group in Clarity AI
peer_group_sizenumber- How many funds are in that peer group
scoreslist- Every score returned
scoring_profiletext- The scoring profile used, such as ESG_RISK_INDUSTRY_CONSENSUS
social_scorenumber- The Social pillar score, 0 to 100
total_scorenumber- The total ESG Risk score, 0 to 100
Example output
{
"allocation_date": "2026-09-30T07:13:25Z",
"coverage_weight": 99.89,
"environmental_score": 58,
"fund_id": "IE00B4L5Y983",
"governance_score": 71,
"id_type": "ISIN",
"name": "iShares Core MSCI World UCITS ETF",
"peer_group_id": "42",
"peer_group_size": 22,
"scores": [
{
"id": "ESG",
"level": "TOTAL",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ESG",
"relevance": 90,
"score": 62
},
{
"id": "ENVIRONMENTAL",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ENVIRONMENTAL",
"relevance": 88,
"score": 58
},
{
"id": "SOCIAL",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "SOCIAL",
"relevance": 91,
"score": 66
},
{
"id": "GOVERNANCE",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "GOVERNANCE",
"relevance": 95,
"score": 71
}
],
"scoring_profile": "ESG_RISK_INDUSTRY_CONSENSUS",
"social_score": 66,
"total_score": 62
}Get fund EU Taxonomy alignment
Get how much of a fund is EU Taxonomy eligible and aligned, for one environmental objective, by turnover, CapEx or OpEx.
Inputs
- Fund ISIN
fund_idtextRequired - The fund's ISIN, such as IE00B4L5Y983.
- Environmental objective
objectivetext - Which EU Taxonomy objective to report on. Defaults to climate change mitigation.One of:
mitigation(Climate change mitigation),adaptation(Climate change adaptation),water(Water and marine resources),circular(Circular economy),pollution(Pollution prevention and control),biodiversity(Biodiversity and ecosystems),aggregation(All objectives together). Default:mitigation. - Measured by
kpitext - Turnover, CapEx or OpEx. Defaults to turnover.One of:
turnover(Turnover (revenue)),capex(Capital expenditure (CapEx)),opex(Operating expenditure (OpEx)). Default:turnover. - Activities
metric_idslist - EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
- Include sovereign bonds
include_sovereign_bondstrue/false - Count government bonds in the totals. Clarity AI leaves them out by default.Default:
false.
Outputs
allocation_datetext- When the fund's holdings were last read
countnumber- How many activities came back
coverage_weightnumber- Share of the fund with data, as a percentage
fund_idtext- The fund's ISIN
metricslist- Each activity asked for, or the total
nametext- The fund's name (empty when Clarity AI doesn't say)
objectivetext- The EU Taxonomy objective
total_organizationsnumber- Companies in the fund
Example output
{
"allocation_date": "2026-09-30T08:17:53.141Z",
"count": 1,
"coverage_weight": 81,
"fund_id": "IE00B4L5Y983",
"metrics": [
{
"aligned": 8.4,
"eligible": 32.5,
"id": "TOTAL",
"metadata": "",
"not_aligned": 85.3,
"not_eligible": 61.2,
"steps": {
"step1": {
"eligible": {
"metadata": "NONE",
"units": "%",
"value": 32.5
},
"notEligible": {
"metadata": "NONE",
"units": "%",
"value": 61.2
}
},
"step5": {
"aligned": {
"metadata": "NONE",
"units": "%",
"value": 8.4
},
"notAligned": {
"metadata": "NONE",
"units": "%",
"value": 85.3
}
}
},
"units": "",
"value": null
}
],
"name": "iShares Core MSCI World UCITS ETF",
"objective": "mitigation",
"total_organizations": 1432
}Get fund exposures
Check whether a fund is exposed to business activities such as coal mining or tobacco, and how much of it is.
Inputs
- Fund ISIN or CUSIP
fund_idtextRequired - The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
- Exposure subjects
subject_idslistRequired - Clarity AI's ids of the business activities to check, such as EXP_COAL_MINING_PART or EXP_TOBACCO_PART, from its data dictionary.
- Use the preview release
preview_releasetrue/false - Read the next data release before it goes live, where Clarity AI has one. Off reads the current release.Default:
false.
Outputs
countnumber- How many subjects came back
exposed_countnumber- How many subjects it is exposed to
exposureslist- Each exposure subject
fund_idtext- The fund's ISIN or CUSIP
id_typetext- ISIN or CUSIP
Example output
{
"count": 2,
"exposed_count": 1,
"exposures": [
{
"category": "ENERGY",
"exposed": false,
"id": "EXP_COAL_MINING_PART",
"level": "SUBJECT",
"weight": 0
},
{
"category": "CONTROVERSIAL_PRODUCTS",
"exposed": true,
"id": "EXP_TOBACCO_PART",
"level": "SUBJECT",
"weight": 1.25
}
],
"fund_id": "IE00B4L5Y983",
"id_type": "ISIN"
}Get fund holdings
Get the companies a fund holds, through any funds inside it, largest first, with their PermIDs for 'Request company data download'. Each account can read 500 different funds a quarter.
Inputs
- Fund ISIN
fund_idtextRequired - The fund's ISIN, such as IE00B4L5Y983.
- How many
limitnumber - The largest this many companies, 1 to 10,000. Defaults to 100.From 1 to 10000.
Outputs
countnumber- How many companies came back
fund_idtext- The fund's ISIN
holdingslist- The companies, largest first
totalnumber- How many companies the fund holds
Example output
{
"count": 2,
"fund_id": "IE00B4L5Y983",
"holdings": [
{
"name": "Apple Inc.",
"perm_id": "4295905573",
"weight": 5.42
},
{
"name": "Microsoft Corp",
"perm_id": "4295907168",
"weight": 4.87
}
],
"total": 1432
}Get portfolio
Get a portfolio's holdings and status. Turn on 'Wait until ready' after creating or updating one, so later steps can read its data.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Wait until ready
wait_until_readytrue/false - Wait while Clarity AI processes a new or changed portfolio, and fail if it rejects it.Default:
false.
Outputs
currencytext- The total's currency, such as USD
holding_countnumber- How many holdings it has
holdingslist- The holdings
idtext- The portfolio's id
is_readytrue/false- True once the portfolio is CREATED and its data can be read
nametext- The portfolio's name
rejection_causetext- Why Clarity AI rejected it (empty unless REJECTED)
statustext- DRAFT or UPDATING while Clarity AI processes it, then CREATED (ready) or REJECTED
total_valuenumber- The portfolio's total value
weightingtext- PERCENTAGE or AMOUNT
Example output
{
"currency": "USD",
"holding_count": 2,
"holdings": [
{
"id": "US0378331005",
"id_type": "ISIN",
"percentage": 60,
"security_type": ""
},
{
"id": "US5949181045",
"id_type": "ISIN",
"percentage": 40,
"security_type": ""
}
],
"id": "650edc5ff188042e8fc2196b",
"is_ready": true,
"name": "Global equity sleeve",
"rejection_cause": "",
"status": "CREATED",
"total_value": 1000000,
"weighting": "PERCENTAGE"
}Get portfolio carbon footprint
Get a portfolio's financed emissions and weighted average carbon intensity (scope 1 and 2), with how much of it is covered.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Outputs
carbon_intensitynumber- Weighted average carbon intensity, scope 1 and 2
countnumber- How many metrics came back
financed_emissionsnumber- Financed emissions, scope 1 and 2
metricslist- The climate metrics
portfolio_idtext- The portfolio's id
portfolio_nametext- The portfolio's name (empty when Clarity AI doesn't say)
total_organizationsnumber- Companies in the portfolio
Example output
{
"carbon_intensity": 89.9,
"count": 2,
"financed_emissions": 742.51,
"metrics": [
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "TOTAL_FINANCED_EMISSIONS_SCOPE_1_2",
"metadata": "NONE",
"name": "Financed emissions (scope 1 and 2)",
"peers_percentile": null,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 742.51
},
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "WEIGHTED_AVERAGE_CARBON_INTENSITY_SCOPE_1_2",
"metadata": "NONE",
"name": "Weighted average carbon intensity (scope 1 and 2)",
"peers_percentile": null,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e / USD M revenue",
"value": 89.9
}
],
"portfolio_id": "650edc5ff188042e8fc2196b",
"portfolio_name": "Global equity sleeve",
"total_organizations": 1957
}Get portfolio climate scores
Get a portfolio's emissions (scope 1, 2 and 3, and the total) and its companies' emission reduction commitments.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Outputs
countnumber- How many metrics came back
metricslist- The climate metrics
portfolio_idtext- The portfolio's id
portfolio_nametext- The portfolio's name (empty when Clarity AI doesn't say)
total_organizationsnumber- Companies in the portfolio
Example output
{
"count": 3,
"metrics": [
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "CO2DIRECTSCOPE1",
"metadata": "NONE",
"name": "Scope 1 CO2e emissions (direct)",
"peers_percentile": null,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 1520.4
},
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "CO2INDIRECTSCOPE2",
"metadata": "NONE",
"name": "Scope 2 CO2e emissions (indirect)",
"peers_percentile": null,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 860.2
},
{
"coverage_organizations": 1344,
"coverage_weight": 87.4,
"id": "CO2INDIRECTSCOPE3",
"metadata": "NONE",
"name": "Scope 3 CO2e emissions (indirect)",
"peers_percentile": null,
"reported_organizations": 957,
"reported_weight": 77.17,
"units": "tons CO2e",
"value": 15230.0
}
],
"portfolio_id": "650edc5ff188042e8fc2196b",
"portfolio_name": "Global equity sleeve",
"total_organizations": 1957
}Get portfolio ESG risk scores
Get a portfolio's ESG Risk score, its Environmental, Social and Governance scores and coverage, or particular scores by id.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Score IDs
score_idslist - Particular ESG Risk scores of the portfolio, such as ENVIRONMENTAL, SOCIAL, GOVERNANCE or a category or metric id from Clarity AI's data dictionary. Leave empty for the total and the three pillars.
Outputs
coverage_weightnumber- Share of the portfolio with ESG data, as a percentage
covered_organizationsnumber- Companies with ESG data
environmental_scorenumber- The Environmental pillar score, 0 to 100
governance_scorenumber- The Governance pillar score, 0 to 100
portfolio_idtext- The portfolio's id
portfolio_nametext- The portfolio's name (empty when Clarity AI doesn't say)
scoreslist- Every score returned
scoring_profiletext- The scoring profile used, such as ESG_RISK_INDUSTRY_CONSENSUS
social_scorenumber- The Social pillar score, 0 to 100
total_organizationsnumber- Companies in the portfolio
total_scorenumber- The total ESG Risk score, 0 to 100
updated_attext- When Clarity AI last updated the scores (empty if not given)
Example output
{
"coverage_weight": 94.85,
"covered_organizations": 673,
"environmental_score": 58,
"governance_score": 71,
"portfolio_id": "650edc5ff188042e8fc2196b",
"portfolio_name": "Global equity sleeve",
"scores": [
{
"id": "ESG",
"level": "TOTAL",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ESG",
"relevance": 90,
"score": 62
},
{
"id": "ENVIRONMENTAL",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ENVIRONMENTAL",
"relevance": 88,
"score": 58
},
{
"id": "SOCIAL",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "SOCIAL",
"relevance": 91,
"score": 66
},
{
"id": "GOVERNANCE",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "GOVERNANCE",
"relevance": 95,
"score": 71
}
],
"scoring_profile": "ESG_RISK_INDUSTRY_CONSENSUS",
"social_score": 66,
"total_organizations": 968,
"total_score": 62,
"updated_at": "2026-10-01T06:20:40Z"
}Get portfolio EU Taxonomy alignment
Get how much of a portfolio is EU Taxonomy eligible and aligned, for one environmental objective, by turnover, CapEx or OpEx.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Environmental objective
objectivetext - Which EU Taxonomy objective to report on. Defaults to climate change mitigation.One of:
mitigation(Climate change mitigation),adaptation(Climate change adaptation),water(Water and marine resources),circular(Circular economy),pollution(Pollution prevention and control),biodiversity(Biodiversity and ecosystems),aggregation(All objectives together). Default:mitigation. - Measured by
kpitext - Turnover, CapEx or OpEx. Defaults to turnover.One of:
turnover(Turnover (revenue)),capex(Capital expenditure (CapEx)),opex(Operating expenditure (OpEx)). Default:turnover. - Activities
metric_idslist - EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
- Include sovereign bonds
include_sovereign_bondstrue/false - Count government bonds in the totals. Clarity AI leaves them out by default.Default:
false.
Outputs
countnumber- How many activities came back
coverage_weightnumber- Share of the portfolio with data, as a percentage
metricslist- Each activity asked for, or the total
objectivetext- The EU Taxonomy objective
portfolio_idtext- The portfolio's id
portfolio_nametext- The portfolio's name (empty when Clarity AI doesn't say)
total_organizationsnumber- Companies in the portfolio
Example output
{
"count": 1,
"coverage_weight": 98.92,
"metrics": [
{
"aligned": 8.4,
"eligible": 32.5,
"id": "TOTAL",
"metadata": "",
"not_aligned": 85.3,
"not_eligible": 61.2,
"steps": {
"step1": {
"eligible": {
"metadata": "NONE",
"units": "%",
"value": 32.5
},
"notEligible": {
"metadata": "NONE",
"units": "%",
"value": 61.2
}
},
"step5": {
"aligned": {
"metadata": "NONE",
"units": "%",
"value": 8.4
},
"notAligned": {
"metadata": "NONE",
"units": "%",
"value": 85.3
}
}
},
"units": "",
"value": null
}
],
"objective": "mitigation",
"portfolio_id": "650edc5ff188042e8fc2196b",
"portfolio_name": "Global equity sleeve",
"total_organizations": 2263
}Get portfolio exposures
Check whether a portfolio is exposed to business activities such as coal mining or tobacco, and how much of it is.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Exposure subjects
subject_idslistRequired - Clarity AI's ids of the business activities to check, such as EXP_COAL_MINING_PART or EXP_TOBACCO_PART, from its data dictionary.
- Use the preview release
preview_releasetrue/false - Read the next data release before it goes live, where Clarity AI has one. Off reads the current release.Default:
false.
Outputs
countnumber- How many subjects came back
exposed_countnumber- How many subjects it is exposed to
exposureslist- Each exposure subject
portfolio_idtext- The portfolio's id
Example output
{
"count": 2,
"exposed_count": 1,
"exposures": [
{
"category": "ENERGY",
"exposed": false,
"id": "EXP_COAL_MINING_PART",
"level": "SUBJECT",
"weight": 0
},
{
"category": "CONTROVERSIAL_PRODUCTS",
"exposed": true,
"id": "EXP_TOBACCO_PART",
"level": "SUBJECT",
"weight": 1.25
}
],
"portfolio_id": "650edc5ff188042e8fc2196b"
}Get portfolio impact highlights
Get a portfolio's environmental and social impact, such as water withdrawn or emissions, also put in everyday terms. Needs at least 5 companies Clarity AI covers.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Outputs
countnumber- How many came back
metricslist- The impact highlights
portfolio_idtext- The portfolio's id
portfolio_nametext- The portfolio's name (empty when Clarity AI doesn't say)
total_organizationsnumber- Companies in the portfolio
updated_attext- When Clarity AI last updated them (empty if not given)
Example output
{
"count": 1,
"metrics": [
{
"converted_units": "Olympic swimming pools",
"converted_value": 400,
"coverage_organizations": 25,
"coverage_weight": 98.2,
"id": "IHL_M_WATER_WITHDRAWAL",
"units": "m3",
"value": 1000000
}
],
"portfolio_id": "650edc5ff188042e8fc2196b",
"portfolio_name": "Global equity sleeve",
"total_organizations": 123,
"updated_at": "2026-10-01T18:26:29.053"
}Get portfolio SFDR indicators
Get a portfolio's SFDR principal adverse impact (PAI) indicators, such as carbon footprint and GHG intensity, with coverage.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Indicators
metric_idslist - SFDR indicator ids, such as CARBON_FOOTPRINT, GHG_INTENSITY or CARBON_EMISSIONS. Leave empty for every indicator.
- Only relevant investments
only_relevant_investmentstrue/false - Work out each indicator over the holdings it applies to, rather than the whole portfolio.Default:
false. - Targeted UN Global Compact method
targeted_m10true/false - Use Clarity AI's targeted methodology for indicator 10 (UN Global Compact and OECD violations) instead of the comprehensive one.Default:
false.
Outputs
countnumber- How many indicators came back
metricslist- The indicators
portfolio_idtext- The portfolio's id
portfolio_nametext- The portfolio's name (empty when Clarity AI doesn't say)
total_organizationsnumber- Companies in the portfolio
Example output
{
"count": 1,
"metrics": [
{
"coverage": 15.38,
"eligibility": 100,
"eligibility_coverage": 15.38,
"id": "CARBON_FOOTPRINT",
"metadata": "NONE",
"percentage_estimated": 0,
"units": "tons CO2e / EUR M invested",
"value": 25.91104
}
],
"portfolio_id": "650edc5ff188042e8fc2196b",
"portfolio_name": "Global equity sleeve",
"total_organizations": 13
}Get top emitting sectors
Get the five industry sectors that contribute most to a portfolio's financed emissions (scope 1 and 2).
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Outputs
countnumber- How many sectors came back
portfolio_idtext- The portfolio's id
sectorslist- The sectors, largest contribution first
Example output
{
"count": 2,
"portfolio_id": "650edc5ff188042e8fc2196b",
"sectors": [
{
"contribution": 39.18,
"metadata": "NONE",
"sector": "Utilities",
"sector_id": "55",
"weight": 2.85
},
{
"contribution": 21.4,
"metadata": "NONE",
"sector": "Materials",
"sector_id": "15",
"weight": 4.1
}
]
}Get top holdings' ESG risk scores
Get the ten largest companies in a portfolio by weight, with each one's ESG Risk and pillar scores.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Outputs
companieslist- The largest companies, by weight
countnumber- How many companies came back
portfolio_idtext- The portfolio's id
Example output
{
"companies": [
{
"company": "Apple Inc",
"environmental_score": 58,
"governance_score": 71,
"scores": [
{
"id": "ESG",
"level": "TOTAL",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ESG",
"relevance": 90,
"score": 62
},
{
"id": "ENVIRONMENTAL",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ENVIRONMENTAL",
"relevance": 88,
"score": 58
},
{
"id": "SOCIAL",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "SOCIAL",
"relevance": 91,
"score": 66
},
{
"id": "GOVERNANCE",
"level": "PILLAR",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "GOVERNANCE",
"relevance": 95,
"score": 71
}
],
"social_score": 66,
"total_score": 62,
"weight": 60
},
{
"company": "Microsoft Corp",
"environmental_score": 70,
"governance_score": 80,
"scores": [
{
"id": "ESG",
"level": "TOTAL",
"metadata": "NONE",
"peers_percentile": null,
"pillar": "ESG",
"relevance": 96,
"score": 74
}
],
"social_score": 72,
"total_score": 74,
"weight": 40
}
],
"count": 2,
"portfolio_id": "650edc5ff188042e8fc2196b"
}List portfolios
List the portfolios in your Clarity AI account, with their ids.
Inputs
- How many
limitnumber - Portfolios per page, 1 to 500. Defaults to 100.From 1 to 500.
- Page
pagenumber - Which page to read, from 1. Defaults to the first.At least 1.
Outputs
countnumber- How many portfolios came back
has_moretrue/false- True when there is another page
pagenumber- The page read, from 1
portfolioslist- The portfolios on this page
totalnumber- How many portfolios the account has
Example output
{
"count": 2,
"has_more": false,
"page": 1,
"portfolios": [
{
"id": "650edc5ff188042e8fc2196b",
"name": "Global equity sleeve"
},
{
"id": "650edc5ff188042e8fc2196c",
"name": "Climate leaders"
}
],
"total": 2
}Look up company IDs
Ask Clarity AI which companies issue a list of securities (ISINs or CUSIPs), or match LEIs to PermIDs. Read the matches with 'Get data download'.
Inputs
- Identifiers
identifierslistRequired - ISINs, CUSIPs, LEIs or PermIDs, all of one kind, one per row or separated by commas.
Outputs
identifier_typetext- What was given: ISIN, CUSIP, LEI or PERMID
job_idtext- The lookup's job id: give it to 'Get data download'
requested_countnumber- How many identifiers were sent
statustext- RUNNING: the lookup is being prepared
Example output
{
"identifier_type": "ISIN",
"job_id": "3b8e8dfc-ee10-408f-9012-00746e46c029",
"requested_count": 2,
"status": "RUNNING"
}Request company data download
Ask Clarity AI for one data set (ESG risk, controversies, carbon footprint, net zero, SFDR and more) for a list of companies by PermID. Read the rows with 'Get data download'.
Inputs
- Data set
datasettext - Which Clarity AI data to download. Defaults to ESG risk scores.One of:
esg_risk(ESG risk scores),controversies,carbon_footprint(Carbon footprint),temperature_alignment(Temperature alignment),net_zero(Net zero transition),sfdr(SFDR principal adverse impacts),exposures(Business activity exposures),impact_highlights(Impact highlights),sustainable_investment(Sustainable investment),nature_tnfd(Nature (TNFD) indicators). Default:esg_risk. - Companies (PermIDs)
perm_idslistRequired - The companies' PermIDs, such as 4295905573, from 'Get fund holdings' or 'Look up company IDs'. Up to 5,000.
- Scores or metrics
metric_idslist - What to include, by Clarity AI id: ESG Risk score ids (ESG, ENVIRONMENTAL, SOCIAL, GOVERNANCE), metric ids (CARBON_EMISSIONS, CARBON_FOOTPRINT, TOTAL.CURRENT_SEVERITY) or exposure ids (EXP_COAL_MINING_PART), from Clarity AI's data dictionary. Leave empty for everything the data set has; ESG risk scores default to the total and three pillars. Exposures need at least one.Only when Data set is ESG risk scores, Controversies, Net zero transition, SFDR principal adverse impacts, Business activity exposures, Impact highlights or Sustainable investment.
Outputs
datasettext- The data set asked for
dataset_nametext- The data set's name
job_idtext- The download's job id: give it to 'Get data download'
metric_idslist- The ids asked for (empty when the data set takes none, or for all)
requested_countnumber- How many securities or companies were asked for
statustext- RUNNING: the download is being prepared
Example output
{
"dataset": "esg_risk",
"dataset_name": "ESG risk scores",
"job_id": "644381ce-93c5-4a6b-b0a7-32a5a62d4acb",
"metric_ids": [
"ESG",
"ENVIRONMENTAL",
"SOCIAL",
"GOVERNANCE"
],
"requested_count": 3,
"status": "RUNNING"
}Request security data download
Ask Clarity AI for one data set (ESG risk, UN Global Compact, carbon footprint, SFDR and more) for a list of shares, bonds or funds. Read the rows with 'Get data download'.
Inputs
- Data set
datasettext - Which Clarity AI data to download. Defaults to ESG risk scores.One of:
esg_risk(ESG risk scores),global_norms(UN Global Compact breaches and watchlist),carbon_footprint(Carbon footprint),temperature_alignment(Temperature alignment),climate_scenarios(Climate scenario analysis),sfdr(SFDR principal adverse impacts),exposures(Business activity exposures),impact_highlights(Impact highlights),nature_biodiversity(Nature and biodiversity impact),sustainable_investment(Sustainable investment),mifid_classifier(MiFID II sustainability preferences),esma_naming(ESMA fund naming exclusions). Default:esg_risk. - Securities
security_idslistRequired - ISINs (or CUSIPs, but not both), one per row or separated by commas, up to 5,000.
- Scores or metrics
metric_idslist - What to include, by Clarity AI id: ESG Risk score ids (ESG, ENVIRONMENTAL, SOCIAL, GOVERNANCE), metric ids (CARBON_EMISSIONS, CARBON_FOOTPRINT, TOTAL.CURRENT_SEVERITY) or exposure ids (EXP_COAL_MINING_PART), from Clarity AI's data dictionary. Leave empty for everything the data set has; ESG risk scores default to the total and three pillars. Exposures need at least one.Only when Data set is ESG risk scores, Carbon footprint, Climate scenario analysis, SFDR principal adverse impacts, Business activity exposures, Impact highlights, Sustainable investment, MiFID II sustainability preferences or ESMA fund naming exclusions.
Outputs
datasettext- The data set asked for
dataset_nametext- The data set's name
job_idtext- The download's job id: give it to 'Get data download'
metric_idslist- The ids asked for (empty when the data set takes none, or for all)
requested_countnumber- How many securities or companies were asked for
statustext- RUNNING: the download is being prepared
Example output
{
"dataset": "esg_risk",
"dataset_name": "ESG risk scores",
"job_id": "644381ce-93c5-4a6b-b0a7-32a5a62d4acb",
"metric_ids": [
"ESG",
"ENVIRONMENTAL",
"SOCIAL",
"GOVERNANCE"
],
"requested_count": 2,
"status": "RUNNING"
}Update portfolio
Replace a portfolio's holdings, and rename it if you like. Clarity AI processes the change in a few seconds.
Inputs
- Portfolio
portfolio_idtextRequired - The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Name
nametext - A new name. Leave empty to keep the current one.
- Holdings
holdingslistRequired - One holding per row: the security's ISIN (or CUSIP, LEI or PermID) and its weight, such as US0378331005, 60. Percentages must add up to 100. A list of records with id and weight from an earlier step works too. A portfolio needs at least two companies.
- Weights are
weightingtext - Whether each holding's weight is a percentage of the portfolio or an amount of money. Defaults to percentages.One of:
PERCENTAGE(Percentages of the portfolio),AMOUNT(Amounts of money). Default:PERCENTAGE. - Total value
total_valuenumber - What the whole portfolio is worth, used for financed emissions. Leave empty to keep the current total.At least 0.01.
- Currency
currencytext - The three-letter currency code of the total and of amounts, such as USD or EUR. Defaults to USD.
- LEI and PermID holdings are
security_typetext - Holdings given by LEI or PermID name a company, not a security: say whether it is held as shares or bonds. Defaults to equity.One of:
EQUITY(Equity (shares)),FIXED_INCOME(Fixed income (bonds)). Default:EQUITY.
Outputs
holding_countnumber- How many holdings it now has
nametext- The portfolio's name
portfolio_idtext- The portfolio's id
statustext- UPDATING: Clarity AI is processing the change
Example output
{
"holding_count": 2,
"name": "Global equity sleeve",
"portfolio_id": "650edc5ff188042e8fc2196b",
"status": "UPDATING"
}