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

# Financials & Earnings Skills

> Reference for financials.income, financials.balance, financials.cashflow, earnings.transcript, earnings.calendar, dividends, and stock.splits — the archive-backed financials and earnings skills exposed to AI agents.

Financials and earnings skills pull statements, transcripts, calendars, dividends, and splits from the Ithaca archive. Statement data comes from **FMP**; transcripts, calendars, dividends, and splits come from the **community archive**.

<Callout type="info">
  Every result includes the [provenance envelope](/skills/overview#the-provenance-envelope). For backtests, prefer `fundamentals.pit` over `financials.*` to avoid lookahead bias on statement data.
</Callout>

## Skill summary

| Skill ID              | Tool name             | Source            | Runtime     | Description                           |
| --------------------- | --------------------- | ----------------- | ----------- | ------------------------------------- |
| `financials.income`   | `financials_income`   | fmp               | interactive | Income statement (annual + quarterly) |
| `financials.balance`  | `financials_balance`  | fmp               | interactive | Balance sheet                         |
| `financials.cashflow` | `financials_cashflow` | fmp               | interactive | Cash flow statement                   |
| `earnings.transcript` | `earnings_transcript` | archive-community | interactive | Earnings call transcript              |
| `earnings.calendar`   | `earnings_calendar`   | archive-community | interactive | Upcoming earnings dates               |
| `dividends`           | `dividends`           | archive-community | interactive | Dividend history + yield              |
| `stock.splits`        | `stock_splits`        | archive-community | interactive | Split history                         |

***

## financials.income

Income statement — revenue, COGS, gross profit, operating income, net income, EPS — annual or quarterly.

**Arguments**

| Name     | Type     | Required | Default    | Description             |
| -------- | -------- | -------- | ---------- | ----------------------- |
| `symbol` | string   | yes      | —          | Ticker symbol           |
| `period` | string   | no       | `annual`   | `annual` or `quarterly` |
| `from`   | ISO date | no       | `now - 5y` | Start period            |
| `to`     | ISO date | no       | latest     | End period              |
| `limit`  | int      | no       | `20`       | Max periods             |

**Source**: `fmp`

**Example**

```json theme={null}
financials_income({ "symbol": "MSFT", "period": "annual", "limit": 3 })
```

```json theme={null}
{
  "skill_id": "financials.income",
  "data": {
    "symbol": "MSFT", "period": "annual",
    "statements": [
      { "fiscal_year": "FY2024", "revenue": 245122000000, "gross_profit": 169198000000, "operating_income": 109429000000, "net_income": 88116000000, "eps": 11.80 },
      { "fiscal_year": "FY2023", "revenue": 211915000000, "gross_profit": 145773000000, "operating_income": 88523000000, "net_income": 72361000000, "eps": 9.68 }
    ]
  },
  "provenance": { "source": "fmp", "freshness": { "as_of": "2025-06-27T22:00:00Z", "lag_seconds": 3600 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## financials.balance

Balance sheet — assets, liabilities, equity, cash, debt.

**Arguments**

| Name     | Type     | Required | Default    | Description             |
| -------- | -------- | -------- | ---------- | ----------------------- |
| `symbol` | string   | yes      | —          | Ticker symbol           |
| `period` | string   | no       | `annual`   | `annual` or `quarterly` |
| `from`   | ISO date | no       | `now - 5y` | Start period            |
| `to`     | ISO date | no       | latest     | End period              |
| `limit`  | int      | no       | `20`       | Max periods             |

**Source**: `fmp`

**Example**

```json theme={null}
financials_balance({ "symbol": "AAPL", "period": "quarterly", "limit": 4 })
```

```json theme={null}
{
  "skill_id": "financials.balance",
  "data": {
    "symbol": "AAPL", "period": "quarterly",
    "statements": [
      { "period": "2025-Q1", "total_assets": 365000000000, "total_liabilities": 290000000000, "total_equity": 75000000000, "cash": 67000000000, "total_debt": 110000000000 }
    ]
  },
  "provenance": { "source": "fmp", "freshness": { "as_of": "2025-06-27T22:00:00Z", "lag_seconds": 3600 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## financials.cashflow

Cash flow statement — operating, investing, financing cash flows + free cash flow.

**Arguments**

| Name     | Type     | Required | Default    | Description             |
| -------- | -------- | -------- | ---------- | ----------------------- |
| `symbol` | string   | yes      | —          | Ticker symbol           |
| `period` | string   | no       | `annual`   | `annual` or `quarterly` |
| `from`   | ISO date | no       | `now - 5y` | Start period            |
| `to`     | ISO date | no       | latest     | End period              |
| `limit`  | int      | no       | `20`       | Max periods             |

**Source**: `fmp`

**Example**

```json theme={null}
financials_cashflow({ "symbol": "NVDA", "period": "annual", "limit": 3 })
```

```json theme={null}
{
  "skill_id": "financials.cashflow",
  "data": {
    "symbol": "NVDA", "period": "annual",
    "statements": [
      { "fiscal_year": "FY2025", "operating_cf": 28100000000, "investing_cf": -6800000000, "financing_cf": -12000000000, "free_cf": 22300000000, "capex": -5800000000 }
    ]
  },
  "provenance": { "source": "fmp", "freshness": { "as_of": "2025-06-27T22:00:00Z", "lag_seconds": 3600 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## earnings.transcript

Earnings call transcript — full text, segmented by speaker.

**Arguments**

| Name         | Type   | Required | Default | Description                |
| ------------ | ------ | -------- | ------- | -------------------------- |
| `symbol`     | string | yes      | —       | Ticker symbol              |
| `quarter`    | string | no       | latest  | e.g. `Q1 2025` or ISO date |
| `include_qa` | bool   | no       | `true`  | Include Q\&A section       |
| `format`     | string | no       | `text`  | `text` or `segments`       |

**Source**: `archive-community`

**Example**

```json theme={null}
earnings_transcript({ "symbol": "NVDA", "quarter": "Q1 2025" })
```

```json theme={null}
{
  "skill_id": "earnings.transcript",
  "data": {
    "symbol": "NVDA", "quarter": "Q1 2025", "date": "2025-05-28",
    "speakers": ["Jensen Huang (CEO)", "Colette Kress (CFO)"],
    "prepared_remarks": "Thank you for joining us today...",
    "qa": [ { "question": "Can you talk about data center demand?", "answer": "..." } ]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-05-28T00:00:00Z", "lag_seconds": 86400 }, "cost": { "credits": 3, "tier": "basic" }, "warnings": [] }
}
```

***

## earnings.calendar

Upcoming earnings dates — confirmed and expected.

**Arguments**

| Name      | Type      | Required | Default     | Description                       |
| --------- | --------- | -------- | ----------- | --------------------------------- |
| `symbols` | string\[] | no       | —           | Filter to specific tickers        |
| `from`    | ISO date  | no       | `now`       | Range start                       |
| `to`      | ISO date  | no       | `now + 30d` | Range end                         |
| `status`  | string    | no       | —           | `confirmed`, `expected`, or `all` |
| `limit`   | int       | no       | `50`        | Max events                        |

**Source**: `archive-community`

**Example**

```json theme={null}
earnings_calendar({ "to": "2025-07-31", "limit": 5 })
```

```json theme={null}
{
  "skill_id": "earnings.calendar",
  "data": {
    "events": [
      { "symbol": "AAPL", "date": "2025-07-31", "time": "after_close", "status": "confirmed", "quarter": "Q3 FY2025" },
      { "symbol": "MSFT", "date": "2025-07-22", "time": "after_close", "status": "confirmed", "quarter": "Q4 FY2025" }
    ]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T18:00:00Z", "lag_seconds": 3600 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

***

## dividends

Dividend history and current yield.

**Arguments**

| Name            | Type     | Required | Default    | Description           |
| --------------- | -------- | -------- | ---------- | --------------------- |
| `symbol`        | string   | yes      | —          | Ticker symbol         |
| `from`          | ISO date | no       | `now - 5y` | Start date            |
| `to`            | ISO date | no       | latest     | End date              |
| `include_yield` | bool     | no       | `true`     | Include current yield |

**Source**: `archive-community`

**Example**

```json theme={null}
dividends({ "symbol": "KO", "from": "2020-01-01" })
```

```json theme={null}
{
  "skill_id": "dividends",
  "data": {
    "symbol": "KO", "current_yield": 0.031, "annual_rate": 1.94,
    "history": [
      { "ex_date": "2025-05-30", "pay_date": "2025-07-01", "amount": 0.485 },
      { "ex_date": "2025-02-14", "pay_date": "2025-04-01", "amount": 0.485 }
    ],
    "growth_5y_cagr": 0.032
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 86400 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

***

## stock.splits

Stock split history — ratio and effective date.

**Arguments**

| Name     | Type     | Required | Default     | Description   |
| -------- | -------- | -------- | ----------- | ------------- |
| `symbol` | string   | yes      | —           | Ticker symbol |
| `from`   | ISO date | no       | `now - 20y` | Start date    |
| `to`     | ISO date | no       | latest      | End date      |

**Source**: `archive-community`

**Example**

```json theme={null}
stock_splits({ "symbol": "NVDA", "from": "2020-01-01" })
```

```json theme={null}
{
  "skill_id": "stock.splits",
  "data": {
    "symbol": "NVDA",
    "splits": [
      { "date": "2024-06-10", "ratio": "10:1", "pre_split_price": 1210.00, "post_split_price": 121.00 },
      { "date": "2021-07-19", "ratio": "4:1", "pre_split_price": 759.12, "post_split_price": 189.78 }
    ]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 86400 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

## Next steps

<Card title="Short Interest Skills" icon="arrow-down" href="/skills/short-interest">
  Short interest, short volume, failures to deliver, and short screens.
</Card>

<Card title="Fundamentals Skills" icon="table-list" href="/skills/fundamentals">
  Fundamentals snapshots, comparisons, point-in-time data, and analyst ratings.
</Card>