> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobalt (Portfolio Monitoring)

> Connect Cobalt to your Agents for read-only access to your private-equity portfolio-monitoring data

## Overview

The [Cobalt](https://www.cobalt.pe) integration (Cobalt is a FactSet company) gives your agents **read-only** access to your Cobalt portfolio-monitoring tenant. Agents can read Portfolios, Funds, Deals, Portfolio Companies, Cashflows, Calculated Values (IRR, MOIC, DPI, TVPI, NAV), Valuation Bridges, and operating Metrics — to answer performance questions, build reporting, and feed analysis, without ever modifying anything in Cobalt.

The integration is read-only by design: the underlying client only issues `GET` requests, so agents cannot create, update, or delete Cobalt data.

## Prerequisites

* A **Cobalt** account with API access
* A Cobalt **API key** (issued per user by Cobalt Support)
* An Aster **admin** to connect the integration (the connection is shared org-wide)

## Setup Guide

<Steps>
  <Step title="Get your Cobalt API key">
    Request an API key from **Cobalt Support**. Cobalt scopes data visibility to the user the key is issued under — make sure that user has access to the portfolios you want your agents to read (see Troubleshooting).
  </Step>

  <Step title="Connect Cobalt in Aster Agents">
    Navigate to **Control Hub > Integrations**, locate the **Cobalt** card, click **Connect**, and paste your API key. Aster validates it against Cobalt and stores it securely for your organization.
  </Step>

  <Step title="Add the Cobalt tool to your agent">
    Edit your agent and enable **Cobalt: Read Portfolio Data** (`cobalt_get`). The agent discovers the available endpoints at runtime and then reads them.
  </Step>
</Steps>

## Available Tools

* **Cobalt: Read Portfolio Data** (`cobalt_get`) — A single tool that fronts the entire read-only Cobalt REST API; your organization's API key is injected automatically.
  * **Self-describing.** The agent calls it with the endpoint `/catalog` first to get the full list of available endpoints, their query parameters, and response fields — no API call is spent.
  * **Reads any endpoint.** The agent then calls a real path (for example `/portfolios`, `/funds`, `/deals`, `/companies`, `/calculated-values`, `/cashflows`, `/metrics/values`) with the appropriate filters.
  * **Large result sets spill to a file.** Big responses are written to a `.json`/`.csv` attachment while the inline payload stays within a token budget, so large pulls don't balloon the agent's context.

### How agents navigate Cobalt

The entity hierarchy is **Portfolios → Funds → Deals → Companies**. The valuable data hangs off those entities:

* **Fund and deal performance** (IRR, MOIC, DPI, TVPI, NAV) is at `/calculated-values`.
* **Per-company operating data** lives in `/custom-field-values` (keyed by `entity_uids`) and `/metrics/values` (keyed by `metric_set_uids`).

So the usual pattern is: list entities first, then pull their values. To discover what exists in your tenant, agents read the meta/list endpoints (`/portfolios`, `/metrics-meta/sets`, `/cashflows-meta`, `/currencies`, `/custom-fields`).

## Example Prompts

Once connected, agents can answer questions like:

* "List our portfolios and the funds in each."
* "What's the net IRR and TVPI for each of our funds as of last quarter?"
* "Pull all contributions and distributions for the Acme deal."
* "Summarize revenue and EBITDA trends for every company in Fund III." (large pulls spill to a CSV the agent can process in Python)

## Notes & Limitations

* **Read-only** — no writes in this release, by design.
* **Per-user data scope** — Cobalt scopes visibility to the user the API key belongs to. The key can authenticate successfully yet return no funds, deals, or companies if that user has not been granted access to your portfolios (see Troubleshooting).
* **Rate limit** — Cobalt allows 100 requests per 120-second window. The tool backs off and retries on rate-limit responses, and agents are guided to prefer bulk endpoints and comma-separated `*_uids` filters over many single calls.
* **No webhooks** — agents poll. For scheduled monitoring, match your task cadence to how fresh you need the data.

## Security Considerations

* **Org-level connection** — one admin connects once for the whole organization. The API key is stored server-side and redacted when the connection is read back in the UI.
* **Read-only by construction** — the client cannot mutate your Cobalt tenant.
* **Grant the Cobalt tool only to agents that need it.**
* **Rotate the key** periodically and reconnect.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection rejected on setup">
    * Confirm the API key was copied exactly and that API access is enabled on your Cobalt account.
  </Accordion>

  <Accordion title="Agents see no funds, deals, or companies (but the key connected fine)">
    This is almost always a **data-access scope** issue, not a missing-data or integration problem. Cobalt ties data visibility to the specific user the API key was issued under. If that user only has access to an empty or limited set of portfolios, the API authenticates but returns empty lists, and some endpoints return `403 No Access`.

    Ask your Cobalt admin to grant that API user access to the relevant portfolios — or issue the key from a service account with firm-wide visibility — then agents will see your funds, deals, companies, and valuations.
  </Accordion>

  <Accordion title="A request feels slow or a large pull is truncated inline">
    * Large responses are written to a `.json`/`.csv` attachment; the inline preview is intentionally truncated to keep the agent's context small. Have the agent process the file (for example in `execute_python`) rather than reading every row inline.
    * Cobalt's rate limit is 100 requests / 120 seconds. For broad questions, guide the agent to use bulk endpoints and comma-separated `*_uids` filters instead of many single calls.
  </Accordion>
</AccordionGroup>

## Related Tools

* [Run Code](/tools/execute_python) — process large Cobalt result sets (the spillover attachment) with pandas.