> ## 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 History

> Retrieve canonical shareholding patterns for an Indian company. By default, the response contains the latest eight periodic observations, newest first. Use filing_basis to select pre-listing or capital-restructuring filings, and as_of_date to select an exact observation date. Headline percentages and total shares are independently source-reported values, so percentages may not sum to exactly 100 and cannot be used to reconstruct exact share counts. Missing categories and unavailable totals are returned as null.

Use this endpoint to see how a company’s ownership is divided among promoters,
foreign institutional investors (FII), domestic institutional investors (DII),
government entities, and the public.

Enter a company ticker, such as `RELIANCE`. By default, the endpoint returns up
to eight canonical periodic observations, ordered from newest to oldest.

## Choose which patterns to return

* `filing_basis` selects the reason for the filing and defaults to `periodic`:
  * `periodic` is a regular reporting-period disclosure.
  * `pre_listing` is a disclosure made before the company’s listing.
  * `capital_restructuring` follows a material change in the company’s capital
    structure.
* For periodic patterns, `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`.
* If you provide `as_of_date` without `filing_basis`, the request still defaults
  to `periodic`.

To explore non-periodic history, select `filing_basis=pre_listing` or
`filing_basis=capital_restructuring` and initially omit `as_of_date`. Add a date
only when you know the exact observation you want. For example, use
`ticker=DANGEE`, `filing_basis=pre_listing`, and `as_of_date=2018-09-01` to
retrieve Dangee Dums’ pre-listing observation.

The response always uses the same collection shape. A request without an exact
date can return up to eight observations. An exact-date request returns zero or
one canonical observation. The API does not substitute an earlier or later
observation when the requested date has no exact match.

## Reading the response

* `data.patterns` contains the matching observations, newest first.
* `as_of_date` is the observation date reported for each filing.
* `filing_basis` identifies why that filing was submitted.
* `total_shares` is the total share count reported in that observation.
* `total_shareholders` is the observation’s reported number of shareholders.
  It may be `null` when the source does not provide it.
* Values under `shareholding` are source-reported percentage points for each
  headline category.

Share counts and percentages are independently source-reported values.
Percentages may not sum to exactly 100 because of rounding, missing categories,
or regulatory classifications.

## Understanding missing values

* `0` means the filing reported zero for that category.
* `null` means the value was unavailable or could not be mapped to that
  headline category.
* `patterns: []` means the ticker identifies a valid company, but no canonical
  observation exactly matches the selected filing basis and date.

To inspect the disclosed holders behind the headline categories, use the
[Shareholding Pattern Holders](/api-reference/india_endpoints/shareholding-holders)
endpoint.


## OpenAPI

````yaml openapi-india get /api/in/v0/shareholding/pattern
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:
    get:
      tags:
        - Shareholding
      summary: Shareholding Pattern History
      description: >-
        Retrieve canonical shareholding patterns for an Indian company. By
        default, the response contains the latest eight periodic observations,
        newest first. Use filing_basis to select pre-listing or
        capital-restructuring filings, and as_of_date to select an exact
        observation date. Headline percentages and total shares are
        independently source-reported values, so percentages may not sum to
        exactly 100 and cannot be used to reconstruct exact share counts.
        Missing categories and unavailable totals are returned as null.
      operationId: getShareholdingPattern
      parameters:
        - $ref: '#/components/parameters/StatementTicker'
        - $ref: '#/components/parameters/ShareholdingFilingBasis'
        - $ref: '#/components/parameters/ShareholdingAsOfDate'
      responses:
        '200':
          description: >-
            Up to eight canonical shareholding observations for the selected
            filing basis and exact date, when provided. A valid company without
            matching observations returns an empty patterns array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareholdingPatternResponse'
              examples:
                periodicHistory:
                  summary: Latest RELIANCE periodic history
                  value:
                    status: success
                    data:
                      company_id: b9b17ea1c7874de79483
                      company_name: Reliance Industries Ltd
                      ticker: RELIANCE
                      patterns:
                        - as_of_date: '2026-06-30'
                          filing_basis: periodic
                          total_shares: 13532538722
                          total_shareholders: 4651863
                          shareholding:
                            promoters: 50.48
                            fii: 17.2
                            dii: 21.19
                            government: 0.1
                            public: 11.04
                        - as_of_date: '2026-03-31'
                          filing_basis: periodic
                          total_shares: 13532472634
                          total_shareholders: 4421289
                          shareholding:
                            promoters: 50
                            fii: 18.67
                            dii: 20.55
                            government: 0.1
                            public: 10.69
                        - as_of_date: '2025-12-31'
                          filing_basis: periodic
                          total_shares: 13532472634
                          total_shareholders: 4206159
                          shareholding:
                            promoters: 50.01
                            fii: 19.09
                            dii: 20.18
                            government: 0.1
                            public: 10.63
                        - as_of_date: '2025-09-30'
                          filing_basis: periodic
                          total_shares: 13532472634
                          total_shareholders: 4393764
                          shareholding:
                            promoters: 50.01
                            fii: 18.65
                            dii: 20.33
                            government: 0.1
                            public: 10.91
                        - as_of_date: '2025-06-30'
                          filing_basis: periodic
                          total_shares: 13532472634
                          total_shareholders: 4435756
                          shareholding:
                            promoters: 50.07
                            fii: 19.21
                            dii: 19.8
                            government: 0.1
                            public: 10.82
                        - as_of_date: '2025-03-31'
                          filing_basis: periodic
                          total_shares: 13532372898
                          total_shareholders: 4765728
                          shareholding:
                            promoters: 50.11
                            fii: 19.06
                            dii: 19.46
                            government: null
                            public: 11.28
                        - as_of_date: '2024-12-31'
                          filing_basis: periodic
                          total_shares: 13532372898
                          total_shareholders: 4714959
                          shareholding:
                            promoters: 50.13
                            fii: 19.15
                            dii: 19.1
                            government: null
                            public: 11.51
                        - as_of_date: '2024-09-30'
                          filing_basis: periodic
                          total_shares: 6766229014
                          total_shareholders: 3834968
                          shareholding:
                            promoters: 50.24
                            fii: 21.29
                            dii: 17.68
                            government: null
                            public: 10.67
                noData:
                  summary: Valid company without matching observations
                  value:
                    status: success
                    data:
                      company_id: b9b17ea1c7874de79483
                      company_name: Reliance Industries Ltd
                      ticker: RELIANCE
                      patterns: []
        '400':
          description: Bad request - Missing or invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                errors:
                  - status: '400'
                    title: Invalid field - as_of_date
                    message: as_of_date must be a valid date in YYYY-MM-DD format
        '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:
    ShareholdingPatternResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: string
          enum:
            - success
        data:
          $ref: '#/components/schemas/ShareholdingPatternData'
    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.
    ShareholdingPatternData:
      type: object
      description: >-
        Company identity and matching canonical shareholding observations.
        Patterns is empty when the company is valid but no filing matches the
        selectors.
      required:
        - company_id
        - company_name
        - ticker
        - patterns
      properties:
        company_id:
          type: string
          description: Internal company identifier.
        company_name:
          type: string
          description: Company name.
        ticker:
          type: string
          description: Canonical company ticker.
        patterns:
          type: array
          maxItems: 8
          description: Matching canonical observations, ordered newest first.
          items:
            $ref: '#/components/schemas/ShareholdingPattern'
    ShareholdingPattern:
      type: object
      description: One canonical shareholding observation.
      required:
        - as_of_date
        - filing_basis
        - total_shares
        - total_shareholders
        - shareholding
      properties:
        as_of_date:
          type: string
          format: date
          description: Observation date reported for the 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.
        shareholding:
          $ref: '#/components/schemas/ShareholdingHeadline'
    ShareholdingHeadline:
      type: object
      description: >-
        Source-reported percentage points for the stable headline categories.
        Missing categories are null, and values may not sum to exactly 100
        because of rounding, missing categories, or regulatory classifications.
      required:
        - promoters
        - fii
        - dii
        - government
        - public
      properties:
        promoters:
          type: number
          nullable: true
          description: Promoter and promoter-group ownership percentage.
        fii:
          type: number
          nullable: true
          description: Foreign institutional investor ownership percentage.
        dii:
          type: number
          nullable: true
          description: Domestic institutional investor ownership percentage.
        government:
          type: number
          nullable: true
          description: Government ownership percentage.
        public:
          type: number
          nullable: true
          description: Other public ownership percentage.
  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

````