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

# 财报日历

> 查询财报和业绩公布事件。

## 套餐权限

| 套餐 | 可用 |
| - | :-: |
| 免费版 | ❌ |
| 基础版 | ✅ |
| 专业版 | ✅ |
| 全量套餐（A 股、港股、美股） | ✅ |
| 企业版 | ✅ |

## 注意事项

* 此接口的事件类别固定为 `report`（财报及业绩公布），无需传入 `category`。
* `from` 默认为当前 UTC 日期；`to` 默认为 `from` 后 7 天。日期范围两端均包含。
* 默认每页 100 条，最多 500 条。第一页不传 `cursor`；后续保持筛选条件不变，并将上一页的 `page.next_cursor` 原样传入，直到其为 `null`。若首次未传日期，后续页请使用首响应的 `data.from`、`data.to` 固定日期范围。
* API Key 仅允许部分市场时，必须传入已获准的 `market`；无对应事件时返回空 `events` 数组。

## 支持的市场

| 市场 | 示例 |
| - | - |
| 美股 | US |
| 港股 | HK |
| A股 | CN |

## 请求参数

| 参数 | 必填 | 说明 |
| - | :-: | - |
| `from` | 否 | 起始日期，格式 `YYYY-MM-DD` |
| `to` | 否 | 结束日期，格式 `YYYY-MM-DD` |
| `market` | 否\* | 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填 |
| `symbols` | 否 | 股票代码，英文逗号分隔，最多 50 个 |
| `limit` | 否 | 每页数量，`1–500`，默认 `100` |
| `cursor` | 否 | 下一页游标；第一页不传 |

## 请求示例

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.tickdb.ai/v1/fundamentals/calendar/report?from=2026-09-21&to=2026-09-28&market=US&limit=100"
```

## 返回字段说明

成功响应包含顶层 `code`、`data` 和 `page`。

| 字段 | 说明 |
| - | - |
| code | 业务状态码，成功为 `0`。 |
| data | 当前页的日期范围和事件数据。 |
| └─ from | 查询起始日期，`YYYY-MM-DD`。 |
| └─ to | 查询结束日期，`YYYY-MM-DD`。 |
| └─ events | 当前页事件列表；无事件时为空数组。 |
|   └─ event\_datetime | 事件时间，UTC 日期时间字符串。 |
|   └─ market | 所属市场。 |
|   └─ symbol | 关联产品代码；不适用时可能为空。 |
|   └─ category | 事件细分类别，可能细于请求类别。 |
|   └─ event\_type | 事件类型。 |
|   └─ content | 事件内容。 |
|   └─ counter\_name | 关联名称；可能为 `null`。 |
|   └─ currency | 币种；可能为 `null`。 |
|   └─ star | 重要程度。 |
|   └─ date\_type | 事件日期类型；可能为 `null`。 |
|   └─ data | 可选的事件附加数据数组。 |
|     └─ key | 附加数据键名。 |
|     └─ value\_raw | 原始值；可能为 `null`。 |
|     └─ value\_text | 展示值；可能为 `null`。 |
|     └─ value\_type | 值类型。 |
| page | 分页信息。 |
| └─ next\_cursor | 下一页游标；末页为 `null`。 |
| └─ limit | 当前分页上限。 |


## OpenAPI

````yaml openapi.yaml GET /v1/fundamentals/calendar/report
openapi: 3.1.0
info:
  title: TickDB API
  description: TickDB 统一实时行情数据 API，提供 REST 和 WebSocket 接入。
  version: 1.0.3
  contact:
    email: support@tickdb.ai
servers:
  - url: https://api.tickdb.ai
    description: 生产环境
security:
  - ApiKeyAuth: []
paths:
  /v1/fundamentals/calendar/report:
    get:
      tags:
        - fundamentals-events
      summary: 财报日历
      description: 查询财报和业绩公布事件。
      operationId: getFundamentalsCalendarReport
      parameters:
        - $ref: '#/components/parameters/CalendarFromQuery'
        - $ref: '#/components/parameters/CalendarToQuery'
        - $ref: '#/components/parameters/CalendarMarketQuery'
        - $ref: '#/components/parameters/CalendarSymbolsQuery'
        - $ref: '#/components/parameters/CalendarLimitQuery'
        - $ref: '#/components/parameters/CursorQuery'
      responses:
        '200':
          $ref: '#/components/responses/CalendarResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    CalendarFromQuery:
      name: from
      in: query
      required: false
      schema:
        type: string
        format: date
      description: 起始日期，格式 `YYYY-MM-DD`
    CalendarToQuery:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date
      description: 结束日期，格式 `YYYY-MM-DD`
    CalendarMarketQuery:
      name: market
      in: query
      required: false
      schema:
        type: string
        enum:
          - US
          - HK
          - CN
      description: 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填
    CalendarSymbolsQuery:
      name: symbols
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        examples:
          - AAPL.US
          - AAPL.US,700.HK,600519.SH
      description: 股票代码，英文逗号分隔，最多 50 个
    CalendarLimitQuery:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
      description: 每页数量，`1–500`，默认 `100`
    CursorQuery:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        minLength: 1
      description: 下一页游标；第一页不传
  responses:
    CalendarResponse:
      description: 财报日历响应。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CalendarEnvelope'
    ErrorResponse:
      description: >-
        错误响应。常见 HTTP 状态包括
        400（参数错误）、401（鉴权失败）、403（权限或配额限制）、404（无匹配数据）、429（请求频率限制）和 503（服务暂不可用）。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            missingAPIKey:
              summary: 缺少 API Key
              value:
                code: '1002'
                message: API key is required. Provide via X-API-Key header
                error: '1002'
            missingKind:
              summary: 缺少必填参数
              value:
                code: 40001
                message: kind is required
                data: null
            endpointForbidden:
              summary: API Key 无权访问该接口
              value:
                code: 3009
                message: This endpoint is not allowed for your API key
                data: null
            marketForbidden:
              summary: API Key 未开放该市场
              value:
                code: 3010
                message: Fundamentals market not allowed for your API key
                data:
                  market: US
            noAvailableSource:
              summary: 数据暂不可用
              value:
                code: 5003
                message: Data is temporarily unavailable
                data: null
            notFound:
              summary: 无匹配数据
              value:
                code: 40404
                message: shareholder detail not found
                data: null
            businessNoData:
              summary: 查询条件无有效业务数据
              value:
                code: 40405
                message: valuation time series not found
                data: null
  schemas:
    CalendarEnvelope:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          required:
            - page
          properties:
            data:
              $ref: '#/components/schemas/CalendarData'
            page:
              $ref: '#/components/schemas/CalendarPage'
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: TickDB API 业务错误码；可能为整数或字符串，客户端应归一化为字符串后比较。
          oneOf:
            - type: integer
            - type: string
        message:
          type: string
          description: 错误说明。
        error:
          type: string
          description: 兼容错误标识；仅部分错误响应返回。
        data:
          description: 可选的错误上下文；可能为 null、对象或数组。
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: true
            - type: array
              items: {}
    SuccessEnvelope:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          const: 0
          description: 业务状态码，成功为 0。
    CalendarData:
      type: object
      required:
        - from
        - to
        - events
      properties:
        from:
          type: string
          format: date
          description: 查询起始日期，闭区间。
        to:
          type: string
          format: date
          description: 查询结束日期，闭区间。
        events:
          type: array
          description: 按 event_datetime 升序排列的财经事件，最多 500 条。
          maxItems: 500
          items:
            $ref: '#/components/schemas/FullCalendarEvent'
      additionalProperties: false
    CalendarPage:
      type: object
      required:
        - next_cursor
        - limit
      properties:
        next_cursor:
          type:
            - string
            - 'null'
          description: 下一页游标；末页为 null。
        limit:
          type: integer
          minimum: 1
          maximum: 500
          description: 当前分页上限。
      additionalProperties: false
    FullCalendarEvent:
      type: object
      required:
        - category
        - content
        - counter_name
        - currency
        - date_type
        - event_datetime
        - event_type
        - market
        - star
        - symbol
      properties:
        category:
          type: string
          description: 事件细分类别，例如 ipo_offering、ipo_listing；请求参数 category 使用上层筛选类别。
        event_datetime:
          type: string
          format: date-time
          description: 事件时间，UTC RFC3339。
        symbol:
          type: string
          description: 标准化股票代码；全局事件可为空字符串。
        market:
          type: string
          enum:
            - US
            - HK
            - CN
          description: 事件所属市场。
        event_type:
          type: string
          description: 事件类型。
        content:
          type: string
          description: 事件内容。
        counter_name:
          type:
            - string
            - 'null'
          description: 相关标的名称。
        date_type:
          type:
            - string
            - 'null'
          description: 日期类型。
        star:
          type: integer
          description: 事件重要性。
        currency:
          type:
            - string
            - 'null'
          description: 币种。
        issue_price:
          type:
            - string
            - 'null'
          description: IPO 发行价格；仅 IPO 事件返回，无可用价格时为 null。
        data:
          type: array
          description: 事件附加数据；没有附加数据时省略。
          items:
            $ref: '#/components/schemas/CalendarEventData'
      additionalProperties: false
    CalendarEventData:
      type: object
      required:
        - key
        - value_type
        - value_text
        - value_raw
      properties:
        key:
          type: string
          description: 附加数据键名，部分记录可能为空字符串。
        value_type:
          type: string
          description: 附加数据类型。
        value_text:
          type:
            - string
            - 'null'
          description: 展示值。
        value_raw:
          type:
            - string
            - 'null'
          description: 原始值。
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.