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

# Shareholding Pattern Holders

> Drill into disclosed holder rows from one canonical shareholding filing. By default, the latest periodic snapshot is selected. Use filing_basis to select a different filing type and as_of_date to select an exact observation. Category and holder-name filters are applied after selecting the snapshot and before pagination. Shares and percentages are independently source-reported values, and a holder category may be null when the source taxonomy cannot be mapped confidently.

Use this endpoint to inspect disclosed holder rows from one canonical filing
selected using the same snapshot controls as the
[Shareholding Pattern](/api-reference/india_endpoints/shareholding-pattern)
endpoint.

## Choose the filing and holders

* `filing_basis` selects `periodic`, `pre_listing`, or
  `capital_restructuring`, and defaults to `periodic`.
* For periodic holders, `as_of_date` selects an exact quarter-end observation.
  Common dates are `2025-03-31`, `2025-06-30`, `2025-09-30`, and
  `2025-12-31`.
* Without `as_of_date`, the endpoint uses the latest canonical filing for the
  selected basis.
* If you provide `as_of_date` without `filing_basis`, the request still defaults
  to `periodic`.

To inspect a non-periodic filing, select `filing_basis=pre_listing` or
`filing_basis=capital_restructuring` and initially omit `as_of_date`; the
endpoint selects the latest filing for that basis. Add a date only when you
know the exact observation you want. The API does not substitute an earlier or
later observation when the requested date has no exact match.

After selecting the filing, narrow its disclosed rows with:

* `category` for one of `promoters`, `fii`, `dii`, `government`, or `public`.
* `q` for a case-insensitive substring search within holder names.
* `page` and `limit` to paginate the matching rows.

For example, use `ticker=JAKHARIA`,
`filing_basis=capital_restructuring`, and `as_of_date=2025-10-09` to
inspect holders disclosed after that capital-structure change.

Category and name filters are applied before pagination. The default page is
`1`, the default limit is `50`, and the maximum limit is `100`.

## Reading the response

* `total_shares` and `total_shareholders` describe the entire filing, not just
  the holders on the current page.
* `as_of_date` and `filing_basis` identify the selected filing.
* `meta.total_count` is the number of disclosed holder rows matching your
  filters before pagination. It is not the company’s total shareholder count.
* `shares` and `percentage` are independently reported for each holder. Keep
  both when exact share counts matter.
* `category` is the stable headline classification used by the API.
* `subcategory` is a more detailed taxonomy-derived classification and may
  evolve as regulatory taxonomies change.

A holder’s `category` can be `null` when the row does not map to one of the five
headline categories. This does not necessarily mean the source classification
is missing; use `subcategory` for the available detail.

This endpoint returns disclosed filing rows, not a complete register of every
shareholder. If no canonical filing matches the selected basis and date, `data`
is `null` and `meta.total_count` is `0`. If the filing exists but no holder rows
match your filters, the filing metadata remains available, `holders` is empty,
and `meta.total_count` is `0`.


## OpenAPI

````yaml openapi-india get /api/in/v0/shareholding/pattern/holders
openapi: 3.0.0
info:
  title: stockinsights.ai APIs
  description: All the APIs of stockinsights.ai
  version: 1.0.0
servers:
  - url: https://stockinsights-ai-main-95a26a0.zuplo.app
security:
  - bearerAuth: []
tags:
  - name: Financial Statements
    description: Financial statements endpoints for Indian companies
  - name: Shareholding
    description: >-
      Historical shareholding patterns and disclosed holders for Indian
      companies
paths:
  /api/in/v0/shareholding/pattern/holders:
    get:
      tags:
        - Shareholding
      summary: Shareholding Pattern Holders
      description: >-
        Drill into disclosed holder rows from one canonical shareholding filing.
        By default, the latest periodic snapshot is selected. Use filing_basis
        to select a different filing type and as_of_date to select an exact
        observation. Category and holder-name filters are applied after
        selecting the snapshot and before pagination. Shares and percentages are
        independently source-reported values, and a holder category may be null
        when the source taxonomy cannot be mapped confidently.
      operationId: getShareholdingPatternHolders
      parameters:
        - $ref: '#/components/parameters/StatementTicker'
        - $ref: '#/components/parameters/ShareholdingFilingBasis'
        - $ref: '#/components/parameters/ShareholdingAsOfDate'
        - name: category
          in: query
          required: false
          description: Optional stable headline category used to filter disclosed holders.
          schema:
            type: string
            enum:
              - promoters
              - fii
              - dii
              - government
              - public
            example: dii
        - name: q
          in: query
          required: false
          description: Optional case-insensitive substring search over holder names.
          schema:
            type: string
            example: mutual
        - name: page
          in: query
          required: false
          description: >-
            Page number after applying the category and holder-name filters.
            Defaults to 1.
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: limit
          in: query
          required: false
          description: Maximum number of holder rows returned per page. Defaults to 50.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            example: 10
      responses:
        '200':
          description: >-
            Disclosed holder rows and pagination metadata from the selected
            canonical filing. Returns null data with a zero total count when no
            filing matches the selectors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareholdingHoldersResponse'
              examples:
                filtered:
                  summary: Filtered RELIANCE holders
                  value:
                    status: success
                    data:
                      company_id: b9b17ea1c7874de79483
                      company_name: Reliance Industries Ltd
                      ticker: RELIANCE
                      as_of_date: '2026-06-30'
                      filing_basis: periodic
                      total_shares: 13532538722
                      total_shareholders: 4651863
                      holders:
                        - holder_name: SBI Mutual Funds
                          category: dii
                          subcategory: mutual_funds_or_uti
                          shares: 347942145
                          percentage: 2.62
                    meta:
                      total_count: 1
                      page: 1
                      limit: 10
                noData:
                  summary: Valid company without a matching filing
                  value:
                    status: success
                    data: null
                    meta:
                      total_count: 0
                      page: 1
                      limit: 50
        '400':
          description: Bad request - Missing or invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                errors:
                  - status: '400'
                    title: Invalid field - filing_basis
                    message: >-
                      Invalid option: expected one of
                      "periodic"|"pre_listing"|"capital_restructuring"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    StatementTicker:
      name: ticker
      in: query
      required: true
      description: >-
        Company ticker symbol. Supports formats: plain ticker (`RELIANCE`),
        exchange-prefixed with dot (`NSE.RELIANCE`, `BSE.RELIANCE`), or colon
        (`NSE:RELIANCE`, `BSE:RELIANCE`), and BSE numeric IDs (`BSE.500325`).
        When no exchange is specified, matches against the generic stock ticker.
      schema:
        type: string
        example: RELIANCE
    ShareholdingFilingBasis:
      name: filing_basis
      in: query
      required: false
      description: Select the normalized filing type. Defaults to `periodic`.
      schema:
        allOf:
          - $ref: '#/components/schemas/ShareholdingFilingBasis'
        default: periodic
        example: periodic
    ShareholdingAsOfDate:
      name: as_of_date
      in: query
      required: false
      description: >-
        Exact source-reported shareholding observation date in `YYYY-MM-DD`
        format. For the default `periodic` filing basis, common observation
        dates are quarter ends such as `2025-03-31`, `2025-06-30`, `2025-09-30`,
        and `2025-12-31`. To discover non-periodic records, select `pre_listing`
        or `capital_restructuring` and initially omit this parameter; provide it
        only when the exact observation date is known. A date-only request still
        defaults to `periodic`, and the API never substitutes an earlier or
        later observation when no exact match exists.
      examples:
        marchQuarterEnd:
          summary: March quarter end
          value: '2025-03-31'
        juneQuarterEnd:
          summary: June quarter end
          value: '2025-06-30'
        septemberQuarterEnd:
          summary: September quarter end
          value: '2025-09-30'
        decemberQuarterEnd:
          summary: December quarter end
          value: '2025-12-31'
      schema:
        type: string
        format: date
  schemas:
    ShareholdingHoldersResponse:
      type: object
      required:
        - status
        - data
        - meta
      properties:
        status:
          type: string
          enum:
            - success
        data:
          $ref: '#/components/schemas/ShareholdingHoldersData'
        meta:
          $ref: '#/components/schemas/ShareholdingHoldersMeta'
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
                description: Error status
              title:
                type: string
                description: Error description
              message:
                type: string
                description: Detailed error message (optional)
    ShareholdingFilingBasis:
      type: string
      enum:
        - periodic
        - pre_listing
        - capital_restructuring
      description: >-
        Normalized reason for the filing: a regular reporting-period disclosure,
        a disclosure before listing, or a disclosure following a material
        capital-structure change.
    ShareholdingHoldersData:
      type: object
      nullable: true
      description: >-
        Disclosed holders from the selected canonical shareholding filing. Null
        when no filing matches the selectors.
      required:
        - company_id
        - company_name
        - ticker
        - as_of_date
        - filing_basis
        - total_shares
        - total_shareholders
        - holders
      properties:
        company_id:
          type: string
          description: Internal company identifier.
        company_name:
          type: string
          description: Company name.
        ticker:
          type: string
          description: Canonical company ticker.
        as_of_date:
          type: string
          format: date
          description: Observation date reported for the selected filing.
        filing_basis:
          $ref: '#/components/schemas/ShareholdingFilingBasis'
        total_shares:
          type: integer
          format: int64
          nullable: true
          description: Source-reported root share count for the filing.
        total_shareholders:
          type: integer
          format: int64
          nullable: true
          description: >-
            Source-reported total number of shareholders, or null when
            unavailable.
        holders:
          type: array
          description: Matching disclosed holder rows after filtering and pagination.
          items:
            $ref: '#/components/schemas/ShareholdingHolder'
    ShareholdingHoldersMeta:
      type: object
      required:
        - total_count
        - page
        - limit
      properties:
        total_count:
          type: integer
          minimum: 0
          description: >-
            Number of disclosed holder rows matching category and holder-name
            filters before pagination.
        page:
          type: integer
          minimum: 1
          description: Requested page number.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: Requested maximum number of rows per page.
    ShareholdingHolder:
      type: object
      required:
        - holder_name
        - category
        - subcategory
        - shares
        - percentage
      properties:
        holder_name:
          type: string
          description: Source-reported holder name.
        category:
          type: string
          nullable: true
          enum:
            - promoters
            - fii
            - dii
            - government
            - public
            - null
          description: >-
            Stable product classification, or null when the holder does not map
            to one of the five headline categories.
        subcategory:
          type: string
          description: >-
            Detailed normalized, taxonomy-derived holder classification. This
            value is informative and may evolve with the regulatory taxonomy.
        shares:
          type: integer
          format: int64
          nullable: true
          description: Source-reported shares held, or null when unavailable.
        percentage:
          type: number
          nullable: true
          description: >-
            Source-reported ownership percentage points, or null when
            unavailable.
      example:
        holder_name: Swiggy Employee Stock Option Trust
        category: null
        subcategory: employee_benefits_trusts
        shares: 140311854
        percentage: 5.08
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: '401'
                title: Unauthorized
                message: Invalid or missing API key
    NotFound:
      description: Company not found for the given ticker
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: '404'
                title: Company not found
                message: 'No company found for ticker: INVALID'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: '500'
                title: Internal Server Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````