# Clarity AI

> Sustainability data for investors: ESG risk scores, carbon footprint, SFDR, EU Taxonomy, controversies and exposures for portfolios, funds and companies.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/clarity-ai

## Actions

### 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 (`name`, text, required): The portfolio's name, unique in your Clarity AI account.
- Holdings (`holdings`, list, required): 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 (`weighting`, text): 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_value`, number): What the whole portfolio is worth, used for financed emissions. Defaults to 1,000,000 when weights are percentages. At least 0.01.
- Currency (`currency`, text): 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_type`, text): 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**

- `currency` (text): The total's currency, such as USD
- `holding_count` (number): How many holdings it has
- `holdings` (list): The holdings
- `id` (text): The portfolio's id
- `is_ready` (true/false): True once the portfolio is CREATED and its data can be read
- `name` (text): The portfolio's name
- `rejection_cause` (text): Why Clarity AI rejected it (empty unless REJECTED)
- `status` (text): DRAFT or UPDATING while Clarity AI processes it, then CREATED (ready) or REJECTED
- `total_value` (number): The portfolio's total value
- `weighting` (text): PERCENTAGE or AMOUNT

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.

**Outputs**

- `deleted` (true/false): Always true
- `portfolio_id` (text): The deleted portfolio's id

**Example output**

```json
{
  "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_isin`, text, required): The ISIN of one of the company's shares or bonds, such as US0378331005.
- Environmental objective (`objective`, text): 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 (`kpi`, text): Turnover, CapEx or OpEx. Defaults to turnover. One of: `turnover` (Turnover (revenue)), `capex` (Capital expenditure (CapEx)), `opex` (Operating expenditure (OpEx)). Default: `turnover`.
- Activities (`metric_ids`, list): EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.

**Outputs**

- `clarity_id` (text): Clarity AI's own id for the company
- `company` (text): The company's name
- `count` (number): How many activities came back
- `isin` (text): The ISIN asked about
- `metrics` (list): Each activity asked for, or the total
- `objective` (text): The EU Taxonomy objective

**Example output**

```json
{
  "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_id`, text, required): The job id a 'Request security data download', 'Request company data download' or 'Look up company IDs' step returned.
- Wait until ready (`wait_until_ready`, true/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_rows`, number): The most rows to return, 1 to 10,000. Defaults to 1,000. From 1 to 10000.

**Outputs**

- `columns` (list): The file's columns, in order
- `is_ready` (true/false): True once the file was read
- `job_id` (text): The download's job id
- `returned_count` (number): How many rows came back
- `row_count` (number): How many rows the file has
- `rows` (list): The file's rows, up to 'Most rows'
- `status` (text): RUNNING, SUCCESS or ERROR, as Clarity AI reports the job
- `truncated` (true/false): True when the file has more rows than came back

**Example output**

```json
{
  "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_id`, text, required): The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
- Amount invested (`invested_amount`, number): The investment to work financed emissions out for. Defaults to 1,000,000. At least 1.
- Currency (`currency`, text): The amount's three-letter currency code, such as USD or EUR. Defaults to USD.

**Outputs**

- `allocation_date` (text): When the fund's holdings were last read
- `carbon_intensity` (number): Weighted average carbon intensity, scope 1 and 2
- `count` (number): How many metrics came back
- `financed_emissions` (number): Financed emissions, scope 1 and 2
- `fund_id` (text): The fund's ISIN or CUSIP
- `id_type` (text): ISIN or CUSIP
- `metrics` (list): The climate metrics
- `name` (text): The fund's name
- `peer_group_id` (text): The fund's peer group in Clarity AI
- `total_organizations` (number): Companies in the fund

**Example output**

```json
{
  "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_id`, text, required): The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.

**Outputs**

- `allocation_date` (text): When the fund's holdings were last read
- `count` (number): How many metrics came back
- `fund_id` (text): The fund's ISIN or CUSIP
- `id_type` (text): ISIN or CUSIP
- `metrics` (list): The climate metrics
- `name` (text): The fund's name
- `peer_group_id` (text): The fund's peer group in Clarity AI
- `total_organizations` (number): Companies in the fund

**Example output**

```json
{
  "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_id`, text, required): The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
- Score IDs (`score_ids`, list): 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_date` (text): When the fund's holdings were last read
- `coverage_weight` (number): Share of the fund with ESG data, as a percentage
- `environmental_score` (number): The Environmental pillar score, 0 to 100
- `fund_id` (text): The fund's ISIN or CUSIP
- `governance_score` (number): The Governance pillar score, 0 to 100
- `id_type` (text): ISIN or CUSIP
- `name` (text): The fund's name (empty when Clarity AI doesn't say)
- `peer_group_id` (text): The fund's peer group in Clarity AI
- `peer_group_size` (number): How many funds are in that peer group
- `scores` (list): Every score returned
- `scoring_profile` (text): The scoring profile used, such as ESG_RISK_INDUSTRY_CONSENSUS
- `social_score` (number): The Social pillar score, 0 to 100
- `total_score` (number): The total ESG Risk score, 0 to 100

**Example output**

```json
{
  "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_id`, text, required): The fund's ISIN, such as IE00B4L5Y983.
- Environmental objective (`objective`, text): 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 (`kpi`, text): Turnover, CapEx or OpEx. Defaults to turnover. One of: `turnover` (Turnover (revenue)), `capex` (Capital expenditure (CapEx)), `opex` (Operating expenditure (OpEx)). Default: `turnover`.
- Activities (`metric_ids`, list): EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
- Include sovereign bonds (`include_sovereign_bonds`, true/false): Count government bonds in the totals. Clarity AI leaves them out by default. Default: `false`.

**Outputs**

- `allocation_date` (text): When the fund's holdings were last read
- `count` (number): How many activities came back
- `coverage_weight` (number): Share of the fund with data, as a percentage
- `fund_id` (text): The fund's ISIN
- `metrics` (list): Each activity asked for, or the total
- `name` (text): The fund's name (empty when Clarity AI doesn't say)
- `objective` (text): The EU Taxonomy objective
- `total_organizations` (number): Companies in the fund

**Example output**

```json
{
  "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_id`, text, required): The fund's ISIN (such as IE00B4L5Y983) or its CUSIP.
- Exposure subjects (`subject_ids`, list, required): 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_release`, true/false): Read the next data release before it goes live, where Clarity AI has one. Off reads the current release. Default: `false`.

**Outputs**

- `count` (number): How many subjects came back
- `exposed_count` (number): How many subjects it is exposed to
- `exposures` (list): Each exposure subject
- `fund_id` (text): The fund's ISIN or CUSIP
- `id_type` (text): ISIN or CUSIP

**Example output**

```json
{
  "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_id`, text, required): The fund's ISIN, such as IE00B4L5Y983.
- How many (`limit`, number): The largest this many companies, 1 to 10,000. Defaults to 100. From 1 to 10000.

**Outputs**

- `count` (number): How many companies came back
- `fund_id` (text): The fund's ISIN
- `holdings` (list): The companies, largest first
- `total` (number): How many companies the fund holds

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Wait until ready (`wait_until_ready`, true/false): Wait while Clarity AI processes a new or changed portfolio, and fail if it rejects it. Default: `false`.

**Outputs**

- `currency` (text): The total's currency, such as USD
- `holding_count` (number): How many holdings it has
- `holdings` (list): The holdings
- `id` (text): The portfolio's id
- `is_ready` (true/false): True once the portfolio is CREATED and its data can be read
- `name` (text): The portfolio's name
- `rejection_cause` (text): Why Clarity AI rejected it (empty unless REJECTED)
- `status` (text): DRAFT or UPDATING while Clarity AI processes it, then CREATED (ready) or REJECTED
- `total_value` (number): The portfolio's total value
- `weighting` (text): PERCENTAGE or AMOUNT

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.

**Outputs**

- `carbon_intensity` (number): Weighted average carbon intensity, scope 1 and 2
- `count` (number): How many metrics came back
- `financed_emissions` (number): Financed emissions, scope 1 and 2
- `metrics` (list): The climate metrics
- `portfolio_id` (text): The portfolio's id
- `portfolio_name` (text): The portfolio's name (empty when Clarity AI doesn't say)
- `total_organizations` (number): Companies in the portfolio

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.

**Outputs**

- `count` (number): How many metrics came back
- `metrics` (list): The climate metrics
- `portfolio_id` (text): The portfolio's id
- `portfolio_name` (text): The portfolio's name (empty when Clarity AI doesn't say)
- `total_organizations` (number): Companies in the portfolio

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Score IDs (`score_ids`, list): 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_weight` (number): Share of the portfolio with ESG data, as a percentage
- `covered_organizations` (number): Companies with ESG data
- `environmental_score` (number): The Environmental pillar score, 0 to 100
- `governance_score` (number): The Governance pillar score, 0 to 100
- `portfolio_id` (text): The portfolio's id
- `portfolio_name` (text): The portfolio's name (empty when Clarity AI doesn't say)
- `scores` (list): Every score returned
- `scoring_profile` (text): The scoring profile used, such as ESG_RISK_INDUSTRY_CONSENSUS
- `social_score` (number): The Social pillar score, 0 to 100
- `total_organizations` (number): Companies in the portfolio
- `total_score` (number): The total ESG Risk score, 0 to 100
- `updated_at` (text): When Clarity AI last updated the scores (empty if not given)

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Environmental objective (`objective`, text): 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 (`kpi`, text): Turnover, CapEx or OpEx. Defaults to turnover. One of: `turnover` (Turnover (revenue)), `capex` (Capital expenditure (CapEx)), `opex` (Operating expenditure (OpEx)). Default: `turnover`.
- Activities (`metric_ids`, list): EU Taxonomy activity ids, such as TOTAL, ENABLING, TRANSITION_ACTIVITY or MANUFACTURE_HYDROGEN. Leave empty for every activity.
- Include sovereign bonds (`include_sovereign_bonds`, true/false): Count government bonds in the totals. Clarity AI leaves them out by default. Default: `false`.

**Outputs**

- `count` (number): How many activities came back
- `coverage_weight` (number): Share of the portfolio with data, as a percentage
- `metrics` (list): Each activity asked for, or the total
- `objective` (text): The EU Taxonomy objective
- `portfolio_id` (text): The portfolio's id
- `portfolio_name` (text): The portfolio's name (empty when Clarity AI doesn't say)
- `total_organizations` (number): Companies in the portfolio

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Exposure subjects (`subject_ids`, list, required): 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_release`, true/false): Read the next data release before it goes live, where Clarity AI has one. Off reads the current release. Default: `false`.

**Outputs**

- `count` (number): How many subjects came back
- `exposed_count` (number): How many subjects it is exposed to
- `exposures` (list): Each exposure subject
- `portfolio_id` (text): The portfolio's id

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.

**Outputs**

- `count` (number): How many came back
- `metrics` (list): The impact highlights
- `portfolio_id` (text): The portfolio's id
- `portfolio_name` (text): The portfolio's name (empty when Clarity AI doesn't say)
- `total_organizations` (number): Companies in the portfolio
- `updated_at` (text): When Clarity AI last updated them (empty if not given)

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Indicators (`metric_ids`, list): SFDR indicator ids, such as CARBON_FOOTPRINT, GHG_INTENSITY or CARBON_EMISSIONS. Leave empty for every indicator.
- Only relevant investments (`only_relevant_investments`, true/false): Work out each indicator over the holdings it applies to, rather than the whole portfolio. Default: `false`.
- Targeted UN Global Compact method (`targeted_m10`, true/false): Use Clarity AI's targeted methodology for indicator 10 (UN Global Compact and OECD violations) instead of the comprehensive one. Default: `false`.

**Outputs**

- `count` (number): How many indicators came back
- `metrics` (list): The indicators
- `portfolio_id` (text): The portfolio's id
- `portfolio_name` (text): The portfolio's name (empty when Clarity AI doesn't say)
- `total_organizations` (number): Companies in the portfolio

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.

**Outputs**

- `count` (number): How many sectors came back
- `portfolio_id` (text): The portfolio's id
- `sectors` (list): The sectors, largest contribution first

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.

**Outputs**

- `companies` (list): The largest companies, by weight
- `count` (number): How many companies came back
- `portfolio_id` (text): The portfolio's id

**Example output**

```json
{
  "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 (`limit`, number): Portfolios per page, 1 to 500. Defaults to 100. From 1 to 500.
- Page (`page`, number): Which page to read, from 1. Defaults to the first. At least 1.

**Outputs**

- `count` (number): How many portfolios came back
- `has_more` (true/false): True when there is another page
- `page` (number): The page read, from 1
- `portfolios` (list): The portfolios on this page
- `total` (number): How many portfolios the account has

**Example output**

```json
{
  "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 (`identifiers`, list, required): ISINs, CUSIPs, LEIs or PermIDs, all of one kind, one per row or separated by commas.

**Outputs**

- `identifier_type` (text): What was given: ISIN, CUSIP, LEI or PERMID
- `job_id` (text): The lookup's job id: give it to 'Get data download'
- `requested_count` (number): How many identifiers were sent
- `status` (text): RUNNING: the lookup is being prepared

**Example output**

```json
{
  "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 (`dataset`, text): 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_ids`, list, required): The companies' PermIDs, such as 4295905573, from 'Get fund holdings' or 'Look up company IDs'. Up to 5,000.
- Scores or metrics (`metric_ids`, list): 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**

- `dataset` (text): The data set asked for
- `dataset_name` (text): The data set's name
- `job_id` (text): The download's job id: give it to 'Get data download'
- `metric_ids` (list): The ids asked for (empty when the data set takes none, or for all)
- `requested_count` (number): How many securities or companies were asked for
- `status` (text): RUNNING: the download is being prepared

**Example output**

```json
{
  "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 (`dataset`, text): 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_ids`, list, required): ISINs (or CUSIPs, but not both), one per row or separated by commas, up to 5,000.
- Scores or metrics (`metric_ids`, list): 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**

- `dataset` (text): The data set asked for
- `dataset_name` (text): The data set's name
- `job_id` (text): The download's job id: give it to 'Get data download'
- `metric_ids` (list): The ids asked for (empty when the data set takes none, or for all)
- `requested_count` (number): How many securities or companies were asked for
- `status` (text): RUNNING: the download is being prepared

**Example output**

```json
{
  "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_id`, text, required): The portfolio. Pick one, or give its id from 'List portfolios' or 'Create portfolio'.
- Name (`name`, text): A new name. Leave empty to keep the current one.
- Holdings (`holdings`, list, required): 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 (`weighting`, text): 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_value`, number): What the whole portfolio is worth, used for financed emissions. Leave empty to keep the current total. At least 0.01.
- Currency (`currency`, text): 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_type`, text): 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_count` (number): How many holdings it now has
- `name` (text): The portfolio's name
- `portfolio_id` (text): The portfolio's id
- `status` (text): UPDATING: Clarity AI is processing the change

**Example output**

```json
{
  "holding_count": 2,
  "name": "Global equity sleeve",
  "portfolio_id": "650edc5ff188042e8fc2196b",
  "status": "UPDATING"
}
```
