# 取得盈餘快照

**API:** Data API

**Endpoint:** `GET /v1/beta/financial/earnings`

**Tags:** Financial Data

單一股票的已公布盈餘，實際值與預估值對照。每筆記錄包含 `report_period`、`fiscal_period`、`filing_date`、`filing_url` 與 `accession_number`，以及一個 `quarterly` 區塊，內含 `revenue`、`estimated_revenue`、`revenue_surprise` 與 `revenue_surprise_pct`，`earnings_per_share` 也有同樣三項，外加年增率變化欄位。它也會傳回 `signals`：上游計算的標記，例如 EPS_BEAT，並附帶 `headline` 及其背後的 `actual` / `estimate` / `surprise_pct`。`ticker` 為必填，也是唯一的參數。用於了解公司實際公布的資料。若需尚未發生的前瞻性共識預估，請用 `get_financial_analyst_estimates`。

### 計費參考

- 計量方式：以成功請求為固定成本基礎。
- 參考請求估算：0.02 美元。
- 參考客戶倍率：1.0。不得對已結算的客戶金額再次應用。

僅供參考的中繼資料，並非帳戶報價、保證價格或消費上限。資源額度並非 Felo 額度。最終費用依 Felo 計費記錄為準。

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | no | string | 來自先前回應 next_page_url 的不透明分頁游標。提供後，其他所有查詢參數都會被忽略：游標會攜帶原始請求的篩選條件。請將其視為不透明值，不要自行建構或修改。 |
| `limit` | query | no | integer, default: 1 | 要傳回的最近 **報告期間** 申報文件數量，依 `(report_period DESC, filing_date ASC)` 排序。如果最近的報告期間同時包含 8-K 和 10-Q / 10-K，傳回的項目數可能超過 `limit`。大於 40 的值會限制為 40。非正數或非整數值傳回 400。這是所有頁面的總數，而非頁面大小：每頁最多包含 10 筆記錄，並透過 `next_page_url` 連結。 |
| `ticker` | query | yes | string | 股票代號（例如 `AAPL`）。 |

## Responses

### 200 — 盈餘回應

Headers:
- `X-Request-Id` (string) — 聯絡 Felo 支援時需提供的請求識別碼。

**application/json**

Schema: `ResponseE40Feb4D3D6B_EarningsResponse` (`#/components/schemas/ResponseE40Feb4D3D6B_EarningsResponse`)

### 400 — 無法處理該要求。請檢查請求參數。

### 401 — 需要有效的 Felo API 金鑰。

### 402 — 由於未符合計費要求，要求無法繼續。

### 403 — 該帳戶無權執行此操作。

### 429 — 已達到要求或支出上限。

### 502 — 服務無法完成該要求。

### 503 — API 或計費服務暫時無法使用。

### 504 — 服務在處理要求時逾時。

### default — 錯誤回應；上游透傳回應可能採用供應商格式

**application/json**

Schema:

```json
{}
```

## Schema definitions

### ResponseE40Feb4D3D6B_EarningsRecord

`#/components/schemas/ResponseE40Feb4D3D6B_EarningsRecord`

```json
{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "description": "要求的 ticker 代碼。"
    },
    "report_period": {
      "type": "string",
      "format": "date",
      "description": "該申報文件涵蓋的報告期間。"
    },
    "fiscal_period": {
      "type": "string",
      "description": "會計期間標籤（例如 2026-Q1 或 2025-FY）。"
    },
    "currency": {
      "type": "string",
      "description": "ISO 貨幣代碼（例如 USD）。"
    },
    "source_type": {
      "type": "string",
      "description": "該申報文件對應的 SEC 表單類型。",
      "enum": [
        "8-K",
        "10-Q",
        "10-K",
        "20-F"
      ]
    },
    "filing_date": {
      "type": "string",
      "format": "date",
      "description": "SEC 受理申報的日曆日，採用美國東部時間（SEC 的營運時區）。與 `filing_datetime` 配對的日曆日。"
    },
    "filing_datetime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "記錄 SEC 受理申報的日內時間戳，採用美國東部時間。取自 SEC EDGAR submissions API 上的 `acceptanceDateTime` 欄位。與 `filing_date` 配對（同一事件的日曆日精度）。"
    },
    "filing_window": {
      "type": [
        "string",
        "null"
      ],
      "description": "SEC 受理申報時的市場時段，依美國東部時間評估。PRE_MARKET = 平日 04:00–09:30 ET。DURING_MARKET = 平日 09:30–16:00 ET。AFTER_HOURS = 平日正常交易時段之外。WEEKEND = 星期六或星期日。當 filing_datetime 無法取得時為 null。",
      "enum": [
        "PRE_MARKET",
        "DURING_MARKET",
        "AFTER_HOURS",
        "WEEKEND"
      ]
    },
    "signals": {
      "type": "array",
      "description": "從該申報文件中提煉、經整理的影響股價洞察。每個項目包含預先算繪的 `headline`、結構化的 `details` 與 `importance` 排名。僅當該項目觸發至少一個訊號時傳回；否則省略該欄位。每個項目最多 8 筆，依 HIGH → MEDIUM → LOW 排序。",
      "items": {
        "$ref": "#/components/schemas/ResponseE40Feb4D3D6B_Signal"
      }
    },
    "filing_url": {
      "type": "string",
      "format": "uri",
      "description": "SEC 申報文件的 URL。"
    },
    "accession_number": {
      "type": "string",
      "description": "識別該申報文件的 SEC accession number。"
    },
    "quarterly": {
      "$ref": "#/components/schemas/ResponseE40Feb4D3D6B_EarningsTimeDimension"
    },
    "annual": {
      "$ref": "#/components/schemas/ResponseE40Feb4D3D6B_EarningsTimeDimension"
    }
  },
  "required": [
    "ticker",
    "report_period",
    "source_type",
    "filing_date",
    "filing_url",
    "accession_number"
  ]
}
```

### ResponseE40Feb4D3D6B_EarningsResponse

`#/components/schemas/ResponseE40Feb4D3D6B_EarningsResponse`

```json
{
  "type": "object",
  "properties": {
    "earnings": {
      "type": "array",
      "description": "該 ticker 的 SEC 申報文件平整清單，依 (report_period DESC, filing_date ASC) 排序。當 `limit=N` 時，最多傳回 N 個 report_period 的申報文件；若最近一個期間同時包含 8-K 與 10-Q/10-K，項目數可能超過 N。",
      "items": {
        "$ref": "#/components/schemas/ResponseE40Feb4D3D6B_EarningsRecord"
      }
    },
    "next_page_url": {
      "type": "string",
      "description": "下一頁結果的絕對 URL。僅在還有更多結果時出現；依原樣要求即可繼續。每頁最多 10 筆記錄。"
    }
  }
}
```

### ResponseE40Feb4D3D6B_EarningsTimeDimension

`#/components/schemas/ResponseE40Feb4D3D6B_EarningsTimeDimension`

```json
{
  "type": "object",
  "properties": {
    "revenue": {
      "type": [
        "number",
        "null"
      ]
    },
    "revenue_chg": {
      "type": "number",
      "description": "營收相對上一期間的百分比變化，以小數表示（例如 0.10 = +10%）。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "revenue_yoy_chg": {
      "type": "number",
      "description": "營收相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "earnings_per_share": {
      "type": [
        "number",
        "null"
      ]
    },
    "earnings_per_share_chg": {
      "type": "number",
      "description": "EPS 相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "earnings_per_share_yoy_chg": {
      "type": "number",
      "description": "EPS 相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "gross_profit": {
      "type": [
        "number",
        "null"
      ]
    },
    "gross_profit_chg": {
      "type": "number",
      "description": "毛利相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "gross_profit_yoy_chg": {
      "type": "number",
      "description": "毛利相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "gross_margin": {
      "type": "number",
      "description": "毛利率，以小數表示（gross_profit / revenue）。僅在可計算時傳回。"
    },
    "gross_margin_chg_bps": {
      "type": "number",
      "description": "毛利率相對上一期間的絕對變化，以基點表示（例如 200.0 = 利潤率擴大 200 bps）。僅在可計算時傳回。"
    },
    "gross_margin_chg_pct": {
      "type": "number",
      "description": "毛利率相對上一期間的百分比變化，以小數表示。僅在可計算時傳回。"
    },
    "gross_margin_yoy_chg_bps": {
      "type": "number",
      "description": "毛利率相對上年同一會計季度的年增變化，以基點表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "gross_margin_yoy_chg_pct": {
      "type": "number",
      "description": "毛利率相對上年同一會計季度的年增百分比變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "operating_income": {
      "type": [
        "number",
        "null"
      ]
    },
    "operating_income_chg": {
      "type": "number",
      "description": "營業利益相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "operating_income_yoy_chg": {
      "type": "number",
      "description": "營業利益相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "operating_margin": {
      "type": "number",
      "description": "營業利益率，以小數表示（operating_income / revenue）。僅在可計算時傳回。"
    },
    "operating_margin_chg_bps": {
      "type": "number",
      "description": "營業利益率相對上一期間的絕對變化，以基點表示。僅在可計算時傳回。"
    },
    "operating_margin_chg_pct": {
      "type": "number",
      "description": "營業利益率相對上一期間的百分比變化，以小數表示。僅在可計算時傳回。"
    },
    "operating_margin_yoy_chg_bps": {
      "type": "number",
      "description": "營業利益率相對上年同一會計季度的年增變化，以基點表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "operating_margin_yoy_chg_pct": {
      "type": "number",
      "description": "營業利益率相對上年同一會計季度的年增百分比變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "net_income": {
      "type": [
        "number",
        "null"
      ]
    },
    "net_income_chg": {
      "type": "number",
      "description": "淨利相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "net_income_yoy_chg": {
      "type": "number",
      "description": "淨利相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "net_margin": {
      "type": "number",
      "description": "淨利率，以小數表示（net_income / revenue）。僅在可計算時傳回。"
    },
    "net_margin_chg_bps": {
      "type": "number",
      "description": "淨利率相對上一期間的絕對變化，以基點表示。僅在可計算時傳回。"
    },
    "net_margin_chg_pct": {
      "type": "number",
      "description": "淨利率相對上一期間的百分比變化，以小數表示。僅在可計算時傳回。"
    },
    "net_margin_yoy_chg_bps": {
      "type": "number",
      "description": "淨利率相對上年同一會計季度的年增變化，以基點表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "net_margin_yoy_chg_pct": {
      "type": "number",
      "description": "淨利率相對上年同一會計季度的年增百分比變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "weighted_average_shares": {
      "type": [
        "number",
        "null"
      ]
    },
    "weighted_average_shares_diluted": {
      "type": [
        "number",
        "null"
      ]
    },
    "cash_and_equivalents": {
      "type": [
        "number",
        "null"
      ]
    },
    "change_in_cash_and_equivalents": {
      "type": [
        "number",
        "null"
      ]
    },
    "total_debt": {
      "type": [
        "number",
        "null"
      ]
    },
    "total_assets": {
      "type": [
        "number",
        "null"
      ]
    },
    "total_liabilities": {
      "type": [
        "number",
        "null"
      ]
    },
    "shareholders_equity": {
      "type": [
        "number",
        "null"
      ]
    },
    "net_cash_flow_from_operations": {
      "type": [
        "number",
        "null"
      ]
    },
    "net_cash_flow_from_operations_chg": {
      "type": "number",
      "description": "營業活動淨現金流相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "net_cash_flow_from_operations_yoy_chg": {
      "type": "number",
      "description": "營業活動淨現金流相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "net_cash_flow_from_investing": {
      "type": [
        "number",
        "null"
      ]
    },
    "net_cash_flow_from_investing_chg": {
      "type": "number",
      "description": "投資活動淨現金流相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "net_cash_flow_from_investing_yoy_chg": {
      "type": "number",
      "description": "投資活動淨現金流相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "net_cash_flow_from_financing": {
      "type": [
        "number",
        "null"
      ]
    },
    "net_cash_flow_from_financing_chg": {
      "type": "number",
      "description": "籌資活動淨現金流相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "net_cash_flow_from_financing_yoy_chg": {
      "type": "number",
      "description": "籌資活動淨現金流相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "capital_expenditure": {
      "type": [
        "number",
        "null"
      ]
    },
    "capital_expenditure_chg": {
      "type": "number",
      "description": "資本支出相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "capital_expenditure_yoy_chg": {
      "type": "number",
      "description": "資本支出相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    },
    "free_cash_flow": {
      "type": [
        "number",
        "null"
      ]
    },
    "free_cash_flow_chg": {
      "type": "number",
      "description": "自由現金流相對上一期間的百分比變化，以小數表示。季度承載內容中為季增率，年度承載內容中為年增率。僅在可計算時傳回。"
    },
    "free_cash_flow_yoy_chg": {
      "type": "number",
      "description": "自由現金流相對上年同一會計季度的年增變化，以小數表示。僅限季度承載內容。僅在可計算時傳回。"
    }
  }
}
```

### ResponseE40Feb4D3D6B_Signal

`#/components/schemas/ResponseE40Feb4D3D6B_Signal`

```json
{
  "type": "object",
  "description": "從該申報文件中提煉、經整理的影響股價洞察。預先算繪的 `headline` 適合直接顯示；`details` 包含用於篩選與程式化使用的結構化欄位。訊號依優先順序傳回（最重要的在前）；`type` 本身即編碼了量級（例如 `STRONG_REVENUE_INCREASE` 與 `REVENUE_INCREASE`）。",
  "required": [
    "type",
    "headline"
  ],
  "properties": {
    "type": {
      "type": "string",
      "description": "訊號類別。MARGIN_EXPANSION/MARGIN_CONTRACTION：毛利率、營業利益率或淨利率中任一項年增變動 ≥100bps。GUIDANCE_RAISED/GUIDANCE_LOWERED/GUIDANCE_REAFFIRMED/GUIDANCE_INITIATED：申報文件中報告的前瞻性財測變化。SEGMENT_OUTPERFORMANCE/SEGMENT_UNDERPERFORMANCE：依有機營收成長計算表現最好或最差的可報告部門。NON_GAAP_DIVERGENCE：調整後/非 GAAP 數字與同期的 GAAP 對應數字存在重大差異。BACKLOG_SURGE/BACKLOG_DECLINE：積壓訂單或剩餘履約義務年增變動 ≥20%。REVENUE_INCREASE/STRONG_REVENUE_INCREASE 及 DECLINE 變體：分級的營收年增變化（≥10% / ≥20% 量級）。NET_INCOME_INCREASE/STRONG_NET_INCOME_INCREASE 及 DECLINE 變體：分級的淨利年增變化（≥15% / ≥30%）。EPS_INCREASE/STRONG_EPS_INCREASE 及 DECLINE 變體：分級的 EPS 年增變化（≥15% / ≥30%）；與淨利相互獨立，因為股份買回會放大 EPS 變動。CAPEX_INCREASE/STRONG_CAPEX_INCREASE 及 DECLINE 變體：分級的資本支出年增變化，以支出量級計（≥15% / ≥30%）。",
      "enum": [
        "MARGIN_EXPANSION",
        "MARGIN_CONTRACTION",
        "GUIDANCE_RAISED",
        "GUIDANCE_LOWERED",
        "GUIDANCE_REAFFIRMED",
        "GUIDANCE_INITIATED",
        "SEGMENT_OUTPERFORMANCE",
        "SEGMENT_UNDERPERFORMANCE",
        "NON_GAAP_DIVERGENCE",
        "BACKLOG_SURGE",
        "BACKLOG_DECLINE",
        "REVENUE_INCREASE",
        "REVENUE_DECLINE",
        "STRONG_REVENUE_INCREASE",
        "STRONG_REVENUE_DECLINE",
        "NET_INCOME_INCREASE",
        "NET_INCOME_DECLINE",
        "STRONG_NET_INCOME_INCREASE",
        "STRONG_NET_INCOME_DECLINE",
        "EPS_INCREASE",
        "EPS_DECLINE",
        "STRONG_EPS_INCREASE",
        "STRONG_EPS_DECLINE",
        "CAPEX_INCREASE",
        "CAPEX_DECLINE",
        "STRONG_CAPEX_INCREASE",
        "STRONG_CAPEX_DECLINE"
      ]
    },
    "metric": {
      "type": [
        "string",
        "null"
      ],
      "description": "該訊號引用的指標（如適用，例如 `revenue`、`earnings_per_share`、`operating_margin`，或財測/KPI 指標名稱）。"
    },
    "period": {
      "type": [
        "string",
        "null"
      ],
      "description": "該訊號引用的會計期間（例如 `2026-Q1`、`FY 2026`）。前瞻財測訊號引用財測期間；財務訊號引用該申報文件的報告期間。"
    },
    "headline": {
      "type": "string",
      "description": "預先算繪的人類可讀摘要，適合直接顯示。"
    },
    "details": {
      "type": "object",
      "description": "特定於訊號類型的結構化欄位。內容因類型而異：財測訊號包含 `low`、`high`、`point_estimate`、`prior_value`、`revision_pct`；部門訊號包含 `best`、`worst`、`spread_pp`；非 GAAP 訊號包含 `gaap_field`、`non_gaap_value`、`gaap_value`、`divergence_pct`；成長訊號包含 `current`、`yoy_chg`。null 值會被省略。請參考各類型的範例。",
      "additionalProperties": true
    }
  }
}
```