# Financials

> API version: v1

Standardized line items per period, newest first. Every value is the trailing twelve months (TTM) ending at the period end; balance sheet items (`total_debt`, `cash_and_equivalents`) are the value at the period end. `period=annual` keeps only the fiscal year ends.

A period is left out when none of the requested items has a value for it, and an item without a value is omitted from `values`.

`GET /api/v1/companies/{symbol}/financials`

Requires an API key in the `X-Api-Key` header.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `symbol` | path | string | yes | Ticker symbol of a listed company, for example `CSCO`. Case-insensitive. |
| `period` | query | string (ttm \| annual) | no | `ttm` (default): the trailing twelve months at each quarter end. `annual`: the fiscal year ends only. Discrete quarters are not available yet. |
| `items` | query | string | no | Comma-separated line items to return. Default: all. One of: `revenue`, `net_income`, `eps_basic`, `dividends_per_share`, `free_cash_flow`, `shares_basic`, `shares_diluted`, `total_debt`, `cash_and_equivalents`, `roic`, `debt_to_fcf`. |
| `from` | query | string | no | Only periods with a period end on or after this date (`YYYY-MM-DD`). |
| `to` | query | string | no | Only periods with a period end on or before this date (`YYYY-MM-DD`). |
| `limit` | query | integer | no | Number of periods. Default 20, maximum 40. |

## Request

**curl**

```bash
curl "https://studyingstocks.com/api/v1/companies/CSCO/financials?period=annual&items=revenue,free_cash_flow&limit=5" \
  -H "X-Api-Key: $STUDYING_STOCKS_API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get("https://studyingstocks.com/api/v1/companies/CSCO/financials", params={"period": "annual", "items": "revenue,free_cash_flow", "limit": "5"}, headers={"X-Api-Key": os.environ["STUDYING_STOCKS_API_KEY"]})
response.raise_for_status()
print(response.json())
```

**JavaScript**

```javascript
const response = await fetch("https://studyingstocks.com/api/v1/companies/CSCO/financials?period=annual&items=revenue,free_cash_flow&limit=5", {
  headers: { "X-Api-Key": process.env.STUDYING_STOCKS_API_KEY },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

## Response

Periods with their values.

```json
{
    "data": [
        {
            "period": "2026Q4",
            "period_end": "2026-07-25",
            "fiscal_year": 2026,
            "fiscal_quarter": 4,
            "values": {
                "revenue": 63325000000,
                "free_cash_flow": 12767000000
            }
        }
    ],
    "meta": {
        "symbol": "CSCO",
        "currency": "USD",
        "period": "ttm",
        "items": [
            "revenue",
            "free_cash_flow"
        ],
        "count": 1,
        "filings_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000858877&type=10-&dateb=&owner=include&count=40",
        "source": "SEC EDGAR",
        "api_version": "v1",
        "generated_at": "2026-10-16T02:00:00Z"
    }
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `data[].period` | string | Fiscal period label: `2026Q4` for TTM periods, `FY2026` for annual ones. |
| `data[].period_end` | string |  |
| `data[].fiscal_year` | integer |  |
| `data[].fiscal_quarter` | integer |  |
| `data[].values` | object | Line items by name; items without a value are omitted. |
| `data[].values.revenue` | number | Revenue. |
| `data[].values.net_income` | number | Net income attributable to common shareholders. |
| `data[].values.eps_basic` | number | Earnings per share, basic. Per-share values are decimals. |
| `data[].values.dividends_per_share` | number | Dividends declared per share. |
| `data[].values.free_cash_flow` | number | Calculated: operating cash flow minus capital expenditure. |
| `data[].values.shares_basic` | number | Weighted average basic shares outstanding. |
| `data[].values.shares_diluted` | number | Weighted average diluted shares outstanding. |
| `data[].values.total_debt` | number | Total debt at the period end (long-term debt, current maturities and short-term borrowings). |
| `data[].values.cash_and_equivalents` | number | Cash, cash equivalents and short-term investments at the period end. |
| `data[].values.roic` | number | Calculated: return on invested capital as a fraction (0.18 = 18%). |
| `data[].values.debt_to_fcf` | number | Calculated: total debt divided by free cash flow, in years. Omitted when free cash flow is not positive. |
| `meta.source` | string | Where the data comes from: always SEC EDGAR (calculated items are derived from it). |
| `meta.api_version` | string |  |
| `meta.generated_at` | string | When this response was generated (responses are cached for a few hours). |
| `meta.symbol` | string |  |
| `meta.currency` | string |  |
| `meta.period` | string |  |
| `meta.items` | array of string |  |
| `meta.count` | integer |  |
| `meta.filings_url` | string or null | SEC's list of the company's periodic filings, where each value can be checked. |

## Errors

| Status | Code | When |
|---|---|---|
| 401 | [`unauthenticated`](https://studyingstocks.com/developers/errors#unauthenticated) | Missing or invalid API key. |
| 403 | [`subscription_inactive`](https://studyingstocks.com/developers/errors#subscription_inactive) | The Premium subscription behind the key is not active. |
| 404 | [`not_found`](https://studyingstocks.com/developers/errors#not_found) | The company is not covered. |
| 422 | [`invalid_parameter`](https://studyingstocks.com/developers/errors#invalid_parameter) | A query parameter is invalid. |
| 429 | [`rate_limited`](https://studyingstocks.com/developers/errors#rate_limited) | Rate limit reached. |
| 500 | [`server_error`](https://studyingstocks.com/developers/errors#server_error) | Something went wrong on our side. |

All errors have the [same shape](https://studyingstocks.com/developers/errors).