# 获取盈利快照

**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
    }
  }
}
```