> ## 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. # Shareholder Holdings > Query major shareholders' holdings, position changes, and detail availability across reporting periods. ## Plan Access | Plan | Available | | - | :-: | | Free | ❌ | | Starter | ❌ | | Professional | ✅ | | Full-Market Plans (A-Shares, HK Stocks, US Stocks) | ✅ | | Enterprise | ✅ | ## Notes * The response contains shareholder records from multiple reporting periods and is not limited to ten shareholders. Only an `object_id` with `detail_available=true` can be used with the shareholder detail endpoint. ## Supported Markets | Market | Examples | | - | - | | US Stocks | AAPL.US | | HK Stocks | 700.HK | | A-Shares | 600519.SH | ## Request Parameters | Parameter | Required | Description | | - | :-: | - | | `symbol` | Yes | Stock symbol | | `type` | No | Product type; currently supports `stock` | ## Request Example ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/shareholders/top?symbol=AAPL&type=stock" ``` ## Response Fields The table below lists fields in `data`; an outer `code=0` indicates success. | Field | Description | | - | - | | symbol | Stock symbol. | | total | Total number of summarized records. | | periods | Available reporting periods. | | info | Shareholder holdings grouped by reporting period. | | └─ period | Reporting period. | | └─ share\_holders | Shareholder list for the reporting period. | |     └─ object\_id | Shareholder object ID. | |     └─ name | Shareholder name. | |     └─ shares\_held | Number of shares held, returned as a string. | |     └─ percent\_shares\_held | Ownership percentage, including the percent sign. | |     └─ shares\_changed | Change in shares. | |     └─ percent\_shares\_changed | Change in ownership percentage, including the percent sign. | |     └─ period | Reporting period for this record. | |     └─ filing\_date | Original filing-date text, for example `2026/05/07`. | | members | Normalized shareholder records. | | └─ shareholder\_name | Shareholder name. | | └─ shareholder\_type | Shareholder type. | | └─ shares\_held | Number of shares held, returned as a string. | | └─ percent\_shares\_held | Ownership percentage value without the percent sign; `null` when it cannot be converted. | | └─ percent\_shares\_held\_raw | Original ownership percentage text, including the percent sign and representations such as `<0.01%`. | | └─ percent\_shares\_changed | Ownership percentage change without the percent sign; `null` when it cannot be converted. | | └─ filing\_date | Filing date in `YYYY-MM-DD` format. | | └─ report\_date | Report date in `YYYY-MM-DD` format; may be `null`. | | └─ object\_id | Shareholder object ID. | | └─ detail\_available | Whether shareholder details can be queried. | Returns shareholder names, institution types, shares held, ownership percentages, report dates, `object_id`, and `detail_available`. Only an `object_id` with `detail_available=true` can be used with the shareholder detail endpoint. ## OpenAPI ````yaml openapi.en.yaml GET /v1/fundamentals/shareholders/top openapi: 3.1.0 info: title: TickDB API description: TickDB unified real-time market data API via REST and WebSocket. version: 1.0.3 contact: email: support@tickdb.ai servers: - url: https://api.tickdb.ai description: Production server security: - ApiKeyAuth: [] paths: /v1/fundamentals/shareholders/top: get: tags: - fundamentals-holders summary: Shareholder Holdings description: >- Query major shareholders' holdings, position changes, and detail availability across reporting periods. operationId: getFundamentalsShareholdersTop parameters: - $ref: '#/components/parameters/SymbolQuery' - $ref: '#/components/parameters/TypeQuery' responses: '200': $ref: '#/components/responses/TopShareholdersResponse' default: $ref: '#/components/responses/ErrorResponse' components: parameters: SymbolQuery: name: symbol in: query required: true schema: type: string examples: - AAPL - '700' - '600519' - AAPL.US - 700.HK - 600519.SH description: Stock symbol TypeQuery: name: type in: query required: false schema: type: string enum: - stock description: Product type; currently supports `stock` responses: TopShareholdersResponse: description: Shareholder Holdings response. content: application/json: schema: $ref: '#/components/schemas/TopShareholdersEnvelope' ErrorResponse: description: >- Error response. Common HTTP statuses include 400 (invalid parameters), 401 (authentication failed), 403 (permission or quota restriction), 404 (no matching data), 429 (rate limit), and 503 (service temporarily unavailable). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: missingAPIKey: summary: Missing API key value: code: '1002' message: API key is required. Provide via X-API-Key header error: '1002' missingKind: summary: Missing required parameter value: code: 40001 message: kind is required data: null endpointForbidden: summary: API key cannot access this endpoint value: code: 3009 message: This endpoint is not allowed for your API key data: null marketForbidden: summary: API key cannot access this market value: code: 3010 message: Fundamentals market not allowed for your API key data: market: US noAvailableSource: summary: Data temporarily unavailable value: code: 5003 message: Data is temporarily unavailable data: null notFound: summary: No matching data value: code: 40404 message: shareholder detail not found data: null businessNoData: summary: No business data matches the query value: code: 40405 message: valuation time series not found data: null schemas: TopShareholdersEnvelope: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/TopShareholdersData' ErrorEnvelope: type: object required: - code - message properties: code: description: >- TickDB API business error code; may be an integer or string. Convert it to a string before comparing. oneOf: - type: integer - type: string message: type: string description: Error description. error: type: string description: >- Compatibility error identifier; present only in some error responses. data: description: Optional error context; may be null, an object, or an array. oneOf: - type: 'null' - type: object additionalProperties: true - type: array items: {} SuccessEnvelope: type: object required: - code - data properties: code: type: integer const: 0 description: Business status code; `0` means success. TopShareholdersData: type: object required: - symbol - total - periods - info - members properties: symbol: type: string description: Stock symbol. total: type: integer description: Total number of summarized records. periods: type: array items: type: string description: Available reporting periods. info: type: array items: $ref: '#/components/schemas/TopShareholderPeriod' description: Shareholder holdings grouped by reporting period. members: type: array description: Normalized shareholder records. items: $ref: '#/components/schemas/TopShareholderMember' additionalProperties: false TopShareholderPeriod: type: object required: - period - share_holders properties: period: type: string description: Reporting period. share_holders: type: array description: Shareholder list for the reporting period. items: $ref: '#/components/schemas/TopShareholderPeriodMember' additionalProperties: false TopShareholderMember: type: object required: - object_id - shareholder_name - shareholder_type - shares_held - percent_shares_held - percent_shares_held_raw - percent_shares_changed - filing_date - report_date - detail_available properties: object_id: type: string description: Shareholder object ID. shareholder_name: type: string description: Shareholder name. shareholder_type: type: - string - 'null' description: Shareholder type. shares_held: type: string description: Number of shares held, returned as a string. percent_shares_held: type: - string - 'null' description: >- Ownership percentage as a number without the percent sign; `null` if it cannot be converted. percent_shares_held_raw: type: string description: >- Original ownership percentage text, including the percent sign and representations such as `<0.01%`. percent_shares_changed: type: - string - 'null' description: >- Ownership percentage change as a number without the percent sign; `null` if it cannot be converted. filing_date: type: string format: date description: Original filing-date text, for example `2026/05/07`. report_date: type: - string - 'null' format: date description: Report date in `YYYY-MM-DD` format; may be `null`. detail_available: type: boolean description: Whether shareholder details can be queried. additionalProperties: false TopShareholderPeriodMember: type: object required: - filing_date - name - object_id - percent_shares_changed - percent_shares_held - period - shares_changed - shares_held properties: filing_date: type: string description: Original filing-date text, for example `2026/05/07`. name: type: string description: Shareholder name. object_id: type: string description: Shareholder object ID. percent_shares_changed: type: string description: Change in ownership percentage, including the percent sign. percent_shares_held: type: string description: Ownership percentage, including the percent sign. period: type: string description: Reporting period. shares_changed: type: string description: Change in shares. shares_held: type: string description: Number of shares held, returned as a string. 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.