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

ActionWhat it does
Create portfolioCreate a portfolio from holdings.
Delete portfolioDelete a portfolio from your Clarity AI account.
Get company EU Taxonomy alignmentGet how much of a company's business is EU Taxonomy eligible and aligned, for one environmental objective, by its ISIN.
Get data downloadRead the rows of a download Clarity AI has prepared, waiting until it is ready if you like.
Get fund carbon footprintGet a fund's weighted average carbon intensity and the emissions financed by an amount invested in it, with peer percentiles.
Get fund climate scoresGet 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 scoresGet 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 alignmentGet how much of a fund is EU Taxonomy eligible and aligned, for one environmental objective, by turnover, CapEx or OpEx.
Get fund exposuresCheck whether a fund is exposed to business activities such as coal mining or tobacco, and how much of it is.
Get fund holdingsGet the companies a fund holds, through any funds inside it, largest first, with their PermIDs for 'Request company data download'.
Get portfolioGet a portfolio's holdings and status.
Get portfolio carbon footprintGet a portfolio's financed emissions and weighted average carbon intensity (scope 1 and 2), with how much of it is covered.
Get portfolio climate scoresGet a portfolio's emissions (scope 1, 2 and 3, and the total) and its companies' emission reduction commitments.
Get portfolio ESG risk scoresGet a portfolio's ESG Risk score, its Environmental, Social and Governance scores and coverage, or particular scores by id.
Get portfolio EU Taxonomy alignmentGet how much of a portfolio is EU Taxonomy eligible and aligned, for one environmental objective, by turnover, CapEx or OpEx.
Get portfolio exposuresCheck whether a portfolio is exposed to business activities such as coal mining or tobacco, and how much of it is.
Get portfolio impact highlightsGet a portfolio's environmental and social impact, such as water withdrawn or emissions, also put in everyday terms.
Get portfolio SFDR indicatorsGet a portfolio's SFDR principal adverse impact (PAI) indicators, such as carbon footprint and GHG intensity, with coverage.
Get top emitting sectorsGet the five industry sectors that contribute most to a portfolio's financed emissions (scope 1 and 2).
Get top holdings' ESG risk scoresGet the ten largest companies in a portfolio by weight, with each one's ESG Risk and pillar scores.
List portfoliosList the portfolios in your Clarity AI account, with their ids.
Look up company IDsAsk Clarity AI which companies issue a list of securities (ISINs or CUSIPs), or match LEIs to PermIDs.
Request company data downloadAsk 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 downloadAsk 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 portfolioReplace 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

NamenametextRequired
The portfolio's name, unique in your Clarity AI account.
HoldingsholdingslistRequired
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 areweightingtext
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 valuetotal_valuenumber
What the whole portfolio is worth, used for financed emissions. Defaults to 1,000,000 when weights are percentages.At least 0.01.
Currencycurrencytext
The three-letter currency code of the total and of amounts, such as USD or EUR. Defaults to USD.
LEI and PermID holdings aresecurity_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

Portfolioportfolio_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 ISINcompany_isintextRequired
The ISIN of one of the company's shares or bonds, such as US0378331005.
Environmental objectiveobjectivetext
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 bykpitext
Turnover, CapEx or OpEx. Defaults to turnover.One of: turnover (Turnover (revenue)), capex (Capital expenditure (CapEx)), opex (Operating expenditure (OpEx)). Default: turnover.
Activitiesmetric_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 IDjob_idtextRequired
The job id a 'Request security data download', 'Request company data download' or 'Look up company IDs' step returned.
Wait until readywait_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 rowsmax_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 CUSIPfund_idtextRequired
The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
Amount investedinvested_amountnumber
The investment to work financed emissions out for. Defaults to 1,000,000.At least 1.
Currencycurrencytext
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 CUSIPfund_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 CUSIPfund_idtextRequired
The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
Score IDsscore_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 ISINfund_idtextRequired
The fund's ISIN, such as IE00B4L5Y983.
Environmental objectiveobjectivetext
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 bykpitext
Turnover, CapEx or OpEx. Defaults to turnover.One of: turnover (Turnover (revenue)), capex (Capital expenditure (CapEx)), opex (Operating expenditure (OpEx)). Default: turnover.
Activitiesmetric_idslist
EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
Include sovereign bondsinclude_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 CUSIPfund_idtextRequired
The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
Exposure subjectssubject_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 releasepreview_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 ISINfund_idtextRequired
The fund's ISIN, such as IE00B4L5Y983.
How manylimitnumber
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

Portfolioportfolio_idtextRequired
The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Wait until readywait_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

Portfolioportfolio_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

Portfolioportfolio_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

Portfolioportfolio_idtextRequired
The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Score IDsscore_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

Portfolioportfolio_idtextRequired
The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Environmental objectiveobjectivetext
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 bykpitext
Turnover, CapEx or OpEx. Defaults to turnover.One of: turnover (Turnover (revenue)), capex (Capital expenditure (CapEx)), opex (Operating expenditure (OpEx)). Default: turnover.
Activitiesmetric_idslist
EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
Include sovereign bondsinclude_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

Portfolioportfolio_idtextRequired
The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Exposure subjectssubject_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 releasepreview_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

Portfolioportfolio_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

Portfolioportfolio_idtextRequired
The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Indicatorsmetric_idslist
SFDR indicator ids, such as CARBON_FOOTPRINT, GHG_INTENSITY or CARBON_EMISSIONS. Leave empty for every indicator.
Only relevant investmentsonly_relevant_investmentstrue/false
Work out each indicator over the holdings it applies to, rather than the whole portfolio.Default: false.
Targeted UN Global Compact methodtargeted_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

Portfolioportfolio_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

Portfolioportfolio_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 manylimitnumber
Portfolios per page, 1 to 500. Defaults to 100.From 1 to 500.
Pagepagenumber
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

IdentifiersidentifierslistRequired
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 setdatasettext
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 metricsmetric_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 setdatasettext
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.
Securitiessecurity_idslistRequired
ISINs (or CUSIPs, but not both), one per row or separated by commas, up to 5,000.
Scores or metricsmetric_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

Portfolioportfolio_idtextRequired
The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
Namenametext
A new name. Leave empty to keep the current one.
HoldingsholdingslistRequired
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 areweightingtext
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 valuetotal_valuenumber
What the whole portfolio is worth, used for financed emissions. Leave empty to keep the current total.At least 0.01.
Currencycurrencytext
The three-letter currency code of the total and of amounts, such as USD or EUR. Defaults to USD.
LEI and PermID holdings aresecurity_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"
}

On this page