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

# Top Issuers

> Ranked list of the top issuers over a date range, combining new issuance and secondary market trade activity. Issuers are ranked by the chosen metric in descending order. Excludes commercial paper and new issues still without a final OS.



## OpenAPI

````yaml post /api/v1/muni_stats_top_issuers
openapi: 3.0.0
info:
  title: Terrapin API
  version: 1.0.0
servers:
  - url: https://terrapinfinance.com
    variables: {}
security:
  - authorization: []
tags: []
paths:
  /api/v1/muni_stats_top_issuers:
    post:
      tags: []
      summary: US municipal bond top issuers
      description: >-
        Ranked list of the top issuers over a date range, combining new issuance
        and secondary market trade activity. Issuers are ranked by the chosen
        metric in descending order. Excludes commercial paper and new issues
        still without a final OS.
      operationId: post_muni_stats_top_issuers
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              end_date: '2025-03-31'
              limit: 10
              rank_by: trade_volume
              start_date: '2025-01-01'
              states:
                - CA
            schema:
              additionalProperties: false
              properties:
                capital_purpose:
                  description: >
                    Capital purpose, indicating whether the bond proceeds are
                    used for new projects, to refund prior bonds, or both.
                  items:
                    enum:
                      - mixed
                      - new money
                      - refunding
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-validate: null
                end_date:
                  description: End of the date range, in ISO-8601 format (YYYY-MM-DD).
                  format: date
                  nullable: false
                  type: string
                  x-check: end_date_gte_start_date
                  x-check-error: end_date must be greater than or equal to start_date
                  x-struct: null
                  x-validate: null
                interest_types:
                  description: >
                    Types of interest:


                    - `fixed rate`: The bond pays a fixed interest rate
                    throughout its life.

                    - `cab`: Capital Appreciation Bond (CAB), interest accrues
                    and is paid at maturity rather than periodically.

                    - `variable rate`: The bond's interest rate can change over
                    time, typically based on a reference rate or formula (e.g.,
                    SOFR, CPI).

                    - `term rate`: The bond pays interest at a rate set for a
                    specific term or period.

                    - `cab-to-fixed`: The bond starts as a capital appreciation
                    bond and converts to a fixed rate bond.

                    - `step rate`: The bond's interest rate increases ("steps
                    up") at predetermined intervals.

                    - `zero rate / discount rate`: A bond that does not pay or
                    accrue interest.
                  items:
                    enum:
                      - cab
                      - cab-to-fixed
                      - fixed rate
                      - step rate
                      - term rate
                      - variable rate
                      - zero rate / discount rate
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-transform: downcase
                  x-validate: null
                is_amt:
                  description: |
                    Whether the bond is an Alternative Minimum Tax (AMT) bond.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_bank_qualified:
                  description: |
                    Whether the bond is bank qualified.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_federally_taxable:
                  description: |
                    Whether the bond is federally taxable.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_green:
                  description: |
                    Whether the bond is a green bond.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_insured:
                  description: |
                    Whether the bond is insured by a bond insurance company.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_pac:
                  description: |
                    Whether the bond is a Planned Amortization Class (PAC) bond.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_social:
                  description: |
                    Whether the bond is a social bond.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                is_sustainable:
                  description: |
                    Whether the bond is a sustainable bond.
                  nullable: false
                  type: boolean
                  x-struct: null
                  x-validate: null
                limit:
                  default: 10
                  description: Maximum number of issuers to return.
                  maximum: 100
                  minimum: 1
                  nullable: false
                  type: integer
                  x-struct: null
                  x-validate: null
                rank_by:
                  default: trade_volume
                  description: >
                    Metric used to rank issuers in descending order:


                    - `new_issuance_par_value`: New issuance par value within
                    the date range.

                    - `new_cusip_count`: Number of newly issued CUSIPs within
                    the date range.

                    - `trade_volume`: Traded par value within the date range.

                    - `trade_count`: Number of trades within the date range.

                    - `traded_cusip_count`: Number of distinct CUSIPs traded
                    within the date range.
                  enum:
                    - new_cusip_count
                    - new_issuance_par_value
                    - trade_count
                    - trade_volume
                    - traded_cusip_count
                  nullable: false
                  type: string
                  x-struct: null
                  x-validate: null
                rating_group:
                  description: >
                    Credit rating group:


                    - `investment_grade`: Bonds with high credit quality,
                    typically considered safe and low risk.

                    - `high_yield`: Bonds with lower credit quality, typically
                    considered riskier and higher yield.
                  enum:
                    - high_yield
                    - investment_grade
                  nullable: true
                  type: string
                  x-struct: null
                  x-validate: null
                seniority:
                  description: >
                    Seniority of the bond, derived from the series name, ordered
                    from most senior to most junior.
                  items:
                    enum:
                      - first_lien
                      - junior
                      - second_lien
                      - senior
                      - subordinate
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-transform: downcase
                  x-validate: null
                sources_of_repayment:
                  description: >
                    Sources of repayment for municipal bonds. Determines how the
                    bond will be repaid.


                    - `Revenue`: Repaid from specific project revenues (e.g.,
                    tolls, utilities).

                    - `General Obligation`: Repaid from the issuer's general
                    fund.

                    - `Double Barrel`: A combination of General Obligation and
                    Revenue sources.
                  items:
                    enum:
                      - Double Barrel
                      - General Obligation
                      - Revenue
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-validate: null
                start_date:
                  description: >-
                    Start of the date range, in ISO-8601 format (YYYY-MM-DD).
                    New issuance is windowed on the bond's dated date and trade
                    metrics on the trade date.
                  format: date
                  nullable: false
                  type: string
                  x-struct: null
                  x-validate: null
                states:
                  description: >
                    US states or territory where the bond is issued (ANSI
                    2-letter code).
                  items:
                    example: IL
                    maxLength: 2
                    minLength: 2
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-transform: upcase
                  x-validate: null
                use_categories:
                  description: >
                    Filter bonds by use categories (middle level of use of funds
                    hierarchy).


                    For the complete taxonomy, see the [Use of Funds
                    Taxonomy](https://docs.terrapinfinance.com/use_of_funds_taxonomy)
                    reference page.
                  items:
                    enum:
                      - airport
                      - bridges
                      - communication
                      - culture
                      - economic development
                      - electrical
                      - essential services
                      - gas
                      - gas prepay
                      - general purpose
                      - health system
                      - higher education
                      - hospitals
                      - industrial development
                      - military housing
                      - miscellaneous
                      - multi-family housing
                      - parking
                      - port
                      - power
                      - pre-school
                      - primary and secondary education
                      - public housing
                      - public transit
                      - recreational
                      - roads
                      - senior living
                      - single family housing
                      - student loan
                      - waste removal
                      - water and sewer
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-transform: downcase
                  x-validate: null
                use_sectors:
                  description: >
                    Filter bonds by use sectors (top level of use of funds
                    hierarchy).


                    For the complete taxonomy, see the [Use of Funds
                    Taxonomy](https://docs.terrapinfinance.com/use_of_funds_taxonomy)
                    reference page.
                  items:
                    enum:
                      - development
                      - education
                      - government
                      - healthcare
                      - housing
                      - miscellaneous
                      - recreation
                      - securitized
                      - transportation
                      - utility
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-transform: downcase
                  x-validate: null
                uses_of_proceeds:
                  description: >
                    Filter bonds by uses of proceeds (most granular level of use
                    of funds hierarchy).


                    For the complete taxonomy, see the [Use of Funds
                    Taxonomy](https://docs.terrapinfinance.com/use_of_funds_taxonomy)
                    reference page.
                  items:
                    enum:
                      - airport
                      - alternative source power
                      - assisted living
                      - broadband
                      - buses
                      - charter school
                      - coal power
                      - combined port authority
                      - community centre
                      - community college
                      - continuing care retirement community
                      - correctional facilities
                      - courts
                      - critical access hospital
                      - development district
                      - electrical infrastructure
                      - ferries
                      - fire
                      - flood control
                      - gas infrastructure
                      - gas power
                      - gas prepay
                      - health system
                      - hospitality
                      - independent living
                      - industrial development
                      - irrigation
                      - library
                      - local hfa multi-family housing
                      - local hfa single family housing
                      - local standalone multi-family housing
                      - local standalone single family housing
                      - military housing
                      - miscellaneous
                      - museum
                      - non-toll bridges
                      - non-toll roads
                      - nuclear power
                      - nursing home
                      - office buildings
                      - parking facilities
                      - parks
                      - police
                      - pollution control
                      - pre-school and daycare
                      - private college
                      - public buildings
                      - public college
                      - public housing
                      - public school district
                      - regional toll bridges
                      - regional toll roads
                      - sewer
                      - shopping centres
                      - solar power
                      - specialty hospital
                      - stadium
                      - standalone hospital
                      - standalone port
                      - standalone public school
                      - state hfa multi-family housing
                      - state hfa single family housing
                      - state toll bridges
                      - state toll roads
                      - storm water
                      - student housing
                      - student loan
                      - telephone
                      - trains
                      - tribal
                      - waste removal
                      - water
                      - wind power
                    nullable: false
                    type: string
                    x-struct: null
                    x-validate: null
                  type: array
                  x-struct: null
                  x-transform: downcase
                  x-validate: null
              required:
                - end_date
                - start_date
              type: object
              x-struct: null
              x-validate: null
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  - entity_id: 1234
                    issuer_name: State of California
                    last_trade_date: '2025-03-31'
                    new_cusip_count: 84
                    new_issuance_par_value: 1250000000
                    trade_count: 4120
                    trade_volume: 530000000
                    traded_cusip_count: 311
                total: 1
              schema:
                additionalProperties: false
                properties:
                  data:
                    description: List of response data objects, often capped to 1000.
                    items:
                      additionalProperties: false
                      properties:
                        entity_id:
                          description: Unique identifier of the issuing entity.
                          nullable: false
                          type: integer
                          x-struct: null
                          x-validate: null
                        issuer_name:
                          description: Name of the issuing entity.
                          nullable: false
                          type: string
                          x-struct: null
                          x-validate: null
                        last_trade_date:
                          description: >-
                            Most recent trade date for the issuer within the
                            date range.
                          format: date
                          nullable: true
                          type: string
                          x-struct: null
                          x-validate: null
                        new_cusip_count:
                          description: >-
                            Number of newly issued CUSIPs for the issuer within
                            the date range.
                          nullable: false
                          type: integer
                          x-struct: null
                          x-validate: null
                        new_issuance_par_value:
                          description: >-
                            New issuance par value for the issuer within the
                            date range.
                          nullable: false
                          type: number
                          x-struct: null
                          x-validate: null
                        trade_count:
                          description: >-
                            Number of trades for the issuer within the date
                            range.
                          nullable: false
                          type: integer
                          x-struct: null
                          x-validate: null
                        trade_volume:
                          description: >-
                            Traded par value for the issuer within the date
                            range.
                          nullable: false
                          type: number
                          x-struct: null
                          x-validate: null
                        traded_cusip_count:
                          description: >-
                            Number of distinct CUSIPs traded for the issuer
                            within the date range.
                          nullable: false
                          type: integer
                          x-struct: null
                          x-validate: null
                      required:
                        - entity_id
                        - issuer_name
                        - last_trade_date
                        - new_cusip_count
                        - new_issuance_par_value
                        - trade_count
                        - trade_volume
                        - traded_cusip_count
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                  total:
                    description: >-
                      Total number of results in the database that match the
                      query filters.
                    type: integer
                    x-struct: null
                    x-validate: null
                required:
                  - data
                  - total
                title: MuniStatsTopIssuersResponse
                type: object
                x-struct: null
                x-validate: null
          description: Ranked issuers
        '401':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Unauthorized
                          type: string
                          x-struct: null
                          x-validate: null
                        reason:
                          example: >-
                            Your account tier does not allow this operation.
                            Contact team@terrapinfinance.com for an upgrade.
                          type: string
                          x-struct: null
                          x-validate: null
                      required:
                        - detail
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                required:
                  - errors
                type: object
                x-struct: null
                x-validate: null
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Payment Required
                          type: string
                          x-struct: null
                          x-validate: null
                        reason:
                          example: >-
                            You have run out of your granted quota for this
                            resource as defined by your account tier. Contact
                            team@terrapinfinance.com for an upgrade.
                          type: string
                          x-struct: null
                          x-validate: null
                      required:
                        - detail
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                required:
                  - errors
                type: object
                x-struct: null
                x-validate: null
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Forbidden
                          type: string
                          x-struct: null
                          x-validate: null
                        reason:
                          example: >-
                            Your account tier does not allow this operation.
                            Contact team@terrapinfinance.com for an upgrade.
                          type: string
                          x-struct: null
                          x-validate: null
                      required:
                        - detail
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                required:
                  - errors
                type: object
                x-struct: null
                x-validate: null
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          example: 'Invalid string. Got: integer'
                          type: string
                          x-struct: null
                          x-validate: null
                        source:
                          properties:
                            pointer:
                              example: /isins/0
                              type: string
                              x-struct: null
                              x-validate: null
                          required:
                            - pointer
                          type: object
                          x-struct: null
                          x-validate: null
                        title:
                          example: Invalid value
                          type: string
                          x-struct: null
                          x-validate: null
                      required:
                        - detail
                        - source
                        - title
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                required:
                  - errors
                type: object
                x-struct: null
                x-validate: null
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Too Many Requests
                          type: string
                          x-struct: null
                          x-validate: null
                        reason:
                          type: string
                          x-struct: null
                          x-validate: null
                      required:
                        - detail
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                required:
                  - errors
                type: object
                x-struct: null
                x-validate: null
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Internal Server Error
                          type: string
                          x-struct: null
                          x-validate: null
                        reason:
                          type: string
                          x-struct: null
                          x-validate: null
                      required:
                        - detail
                      type: object
                      x-struct: null
                      x-validate: null
                    type: array
                    x-struct: null
                    x-validate: null
                required:
                  - errors
                type: object
                x-struct: null
                x-validate: null
          description: Internal Server Error
      callbacks: {}
components:
  securitySchemes:
    authorization:
      scheme: bearer
      type: http

````