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

# Moody's Instrument Ratings

> Requires an existing license with Moody's.

Every rating action Moody's published on a municipal security. Pass `isins`
for the ratings of those securities, `updated_since` for every rating added
or changed since that UTC instant, or both. Ratings often arrive days after
their `rating_date`, and `updated_since` still returns them.

Moody's deletes rating records as well as publishing them. With
`updated_since`, deleted records are returned too, with `is_deleted` true,
so an incremental pull can drop them.

Moody's can leave a superseded action unterminated next to its successor, so
a security's current rating in a rating class is its newest action there
without a `rating_termination_date`. The issuer and obligor ratings are under
`muni_ratings_moodys_orgs`, by `issuer_organization_id` and
`obligor_organization_id`.


> [!WARNING]
>
> Access requires an existing license with Moody's.


## OpenAPI

````yaml post /api/v1/muni_ratings_moodys_instruments
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_ratings_moodys_instruments:
    post:
      tags: []
      summary: Moody's municipal bond instrument ratings
      description: >
        Requires an existing license with Moody's.


        Every rating action Moody's published on a municipal security. Pass
        `isins`

        for the ratings of those securities, `updated_since` for every rating
        added

        or changed since that UTC instant, or both. Ratings often arrive days
        after

        their `rating_date`, and `updated_since` still returns them.


        Moody's deletes rating records as well as publishing them. With

        `updated_since`, deleted records are returned too, with `is_deleted`
        true,

        so an incremental pull can drop them.


        Moody's can leave a superseded action unterminated next to its
        successor, so

        a security's current rating in a rating class is its newest action there

        without a `rating_termination_date`. The issuer and obligor ratings are
        under

        `muni_ratings_moodys_orgs`, by `issuer_organization_id` and

        `obligor_organization_id`.
      operationId: post_muni_ratings_moodys_instruments
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              isins:
                - US1966324Q32
              updated_since: '2026-08-01T00:00:00Z'
            schema:
              additionalProperties: false
              properties:
                cursor:
                  description: >-
                    The `next_cursor` of the previous page. Leave out, or send
                    `null`, for the first page. Only `cursor` and `limit` may
                    change between pages. See
                    [Pagination](https://docs.terrapinfinance.com/pagination).
                  nullable: true
                  type: string
                isins:
                  description: >-
                    International Securities Identification Number (ISIN),
                    unique 12-character code for the security.
                  items:
                    example: US64966HW301
                    maxLength: 12
                    minLength: 12
                    nullable: false
                    type: string
                  type: array
                  x-check: valid_check_digit
                  x-check-error: Invalid ISIN check digit
                  x-transform: upcase
                limit:
                  default: 100
                  description: >-
                    Number of results per page, at most your tier's [response
                    size
                    limit](https://docs.terrapinfinance.com/rate-limits-and-quotas#response-size-limits).
                    A limit of 0 returns only `total`, the number of matching
                    results.
                  minimum: 0
                  type: integer
                sort:
                  description: >-
                    Fields to sort by. Prefix a field with '-' for descending
                    order. Results with no value come last. See
                    [Order](https://docs.terrapinfinance.com/pagination#order)
                    for how ties are broken.
                  items:
                    enum:
                      - '-cusip'
                      - '-duration_code'
                      - '-duration_text'
                      - '-is_deleted'
                      - '-issuer_legal_name'
                      - '-issuer_organization_id'
                      - '-moodys_instrument_id'
                      - '-moodys_rating_id'
                      - '-obligor_legal_name'
                      - '-obligor_organization_id'
                      - '-rating_class_number'
                      - '-rating_class_text'
                      - '-rating_date'
                      - '-rating_direction_code'
                      - '-rating_direction_text'
                      - '-rating_termination_date'
                      - '-rating_text'
                      - '-rating_type_code'
                      - '-rating_type_text'
                      - '-seniority_code'
                      - '-seniority_text'
                      - '-shadow_code'
                      - '-shadow_text'
                      - '-updated_at'
                      - '-watchlist_date'
                      - '-watchlist_direction_code'
                      - '-watchlist_direction_text'
                      - '-watchlist_termination_date'
                      - cusip
                      - duration_code
                      - duration_text
                      - is_deleted
                      - issuer_legal_name
                      - issuer_organization_id
                      - moodys_instrument_id
                      - moodys_rating_id
                      - obligor_legal_name
                      - obligor_organization_id
                      - rating_class_number
                      - rating_class_text
                      - rating_date
                      - rating_direction_code
                      - rating_direction_text
                      - rating_termination_date
                      - rating_text
                      - rating_type_code
                      - rating_type_text
                      - seniority_code
                      - seniority_text
                      - shadow_code
                      - shadow_text
                      - updated_at
                      - watchlist_date
                      - watchlist_direction_code
                      - watchlist_direction_text
                      - watchlist_termination_date
                    type: string
                  type: array
                  x-transform: downcase
                updated_since:
                  description: >
                    Optional filter to only return ratings added or changed
                    since the given UTC instant.


                    Accepts an ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ).


                    To poll for updates, pass the time you requested the first
                    page of your previous poll,

                    then upsert the results by `moodys_instrument_id`,
                    `rating_class_number` and

                    `rating_date`: some may be ratings you already have.
                  format: date-time
                  nullable: false
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  - cusip: 1966324Q3
                    duration_code: LT
                    duration_text: Long Term Debt Rating
                    is_deleted: false
                    isin: US1966324Q32
                    issuer_legal_name: CHARLESTON (CITY OF) SC
                    issuer_organization_id: '600012345'
                    moodys_instrument_id: '987654321'
                    moodys_rating_id: '123456789'
                    obligor_legal_name: CHARLESTON (CITY OF) SC
                    obligor_organization_id: '600012345'
                    rating_class_number: '1'
                    rating_class_text: LT SR UNSECURED
                    rating_date: '2026-08-01T00:00:00Z'
                    rating_direction_code: UP
                    rating_direction_text: Upgraded
                    rating_termination_date: null
                    rating_text: Aa2
                    rating_type_code: LTD
                    rating_type_text: Long-Term Debt Rating
                    seniority_code: SR
                    seniority_text: Senior Unsecured
                    shadow_code: U
                    shadow_text: Underlying
                    updated_at: '2026-08-01T12:00:00Z'
                    watchlist_date: null
                    watchlist_direction_code: null
                    watchlist_direction_text: null
                    watchlist_termination_date: null
                next_cursor: null
                total: 1
              schema:
                additionalProperties: false
                properties:
                  data:
                    description: >-
                      One page of at most `limit` results. See
                      [Pagination](https://docs.terrapinfinance.com/pagination).
                    items:
                      additionalProperties: false
                      properties:
                        cusip:
                          description: CUSIP of the rated municipal security.
                          example: 1966324Q3
                          nullable: false
                          type: string
                        duration_code:
                          description: Moody's duration code.
                          nullable: true
                          type: string
                        duration_text:
                          description: Duration, e.g. `Long Term Debt Rating`.
                          nullable: true
                          type: string
                        is_deleted:
                          description: >-
                            Whether Moody's deleted this record. Deleted records
                            are only returned with `updated_since`, so an
                            incremental pull can drop them.
                          nullable: false
                          type: boolean
                        isin:
                          description: >-
                            US ISIN computed from the rating's CUSIP. `null`
                            when the CUSIP is missing or not 9 characters.
                          example: US1966324Q32
                          maxLength: 12
                          minLength: 12
                          nullable: true
                          type: string
                        issuer_legal_name:
                          description: The issuer's name as registered with Moody's.
                          nullable: true
                          type: string
                        issuer_organization_id:
                          description: >-
                            Moody's identifier of the security's current issuer.
                            Its ratings are under `muni_ratings_moodys_orgs`.
                          nullable: true
                          type: string
                        moodys_instrument_id:
                          description: Moody's identifier for the rated security.
                          nullable: false
                          type: string
                        moodys_rating_id:
                          description: >-
                            Moody's identifier for this rating record. Stable
                            across updates.
                          nullable: false
                          type: string
                        obligor_legal_name:
                          description: The obligor's name as registered with Moody's.
                          nullable: true
                          type: string
                        obligor_organization_id:
                          description: >-
                            Moody's identifier of the security's current
                            obligor. Its ratings are under
                            `muni_ratings_moodys_orgs`.
                          nullable: true
                          type: string
                        rating_class_number:
                          description: Moody's numeric rating-class identifier.
                          nullable: false
                          type: string
                        rating_class_text:
                          description: Rating class, e.g. `LT SR DEP UNDERLYING`.
                          nullable: true
                          type: string
                        rating_date:
                          description: >-
                            Datetime of the last rating action, excluding
                            confirmations, in UTC. This is a datetime and not a
                            date because that is how Moody's reports it.
                          format: date-time
                          nullable: false
                          type: string
                        rating_direction_code:
                          description: Direction of the most recent rating action.
                          nullable: true
                          type: string
                        rating_direction_text:
                          description: >-
                            Direction of the most recent rating action, e.g.
                            `Upgraded`.
                          example: Upgraded
                          nullable: true
                          type: string
                        rating_termination_date:
                          description: >-
                            Datetime the rating action was terminated, in UTC.
                            This is a datetime and not a date because that is
                            how Moody's reports it. `null` if still current.
                          format: date-time
                          nullable: true
                          type: string
                        rating_text:
                          description: Moody's rating value, e.g. `Aa2`.
                          example: Aa2
                          nullable: false
                          type: string
                        rating_type_code:
                          description: Moody's rating-type code.
                          nullable: true
                          type: string
                        rating_type_text:
                          description: Type of rating, e.g. `Long-Term Debt Rating`.
                          nullable: true
                          type: string
                        seniority_code:
                          description: Moody's seniority code.
                          nullable: true
                          type: string
                        seniority_text:
                          description: Seniority, e.g. `Senior Secured`.
                          nullable: true
                          type: string
                        shadow_code:
                          description: >-
                            Moody's shadow code: insured, enhanced, or
                            underlying.
                          nullable: true
                          type: string
                        shadow_text:
                          description: >-
                            Rating perspective, e.g. `Underlying`, `Insured`,
                            `Enhanced`.
                          nullable: true
                          type: string
                        updated_at:
                          description: >-
                            When Terrapin last added or changed this rating, in
                            UTC. `updated_since` filters on this.
                          format: date-time
                          nullable: false
                          type: string
                        watchlist_date:
                          description: >-
                            Datetime the rating was placed on Moody's watchlist,
                            in UTC. `null` if it never was. A superseded action
                            keeps the watchlist state it had.
                          format: date-time
                          nullable: true
                          type: string
                        watchlist_direction_code:
                          description: Moody's code for the watchlist direction.
                          nullable: true
                          type: string
                        watchlist_direction_text:
                          description: >-
                            Watchlist direction, e.g. `Possible Downgrade`,
                            `Direction Uncertain`.
                          example: Possible Downgrade
                          nullable: true
                          type: string
                        watchlist_termination_date:
                          description: >-
                            Datetime the rating came off the watchlist, in UTC.
                            `null` while it is on it.
                          format: date-time
                          nullable: true
                          type: string
                      required:
                        - cusip
                        - duration_code
                        - duration_text
                        - is_deleted
                        - isin
                        - issuer_legal_name
                        - issuer_organization_id
                        - moodys_instrument_id
                        - moodys_rating_id
                        - obligor_legal_name
                        - obligor_organization_id
                        - rating_class_number
                        - rating_class_text
                        - rating_date
                        - rating_direction_code
                        - rating_direction_text
                        - rating_termination_date
                        - rating_text
                        - rating_type_code
                        - rating_type_text
                        - seniority_code
                        - seniority_text
                        - shadow_code
                        - shadow_text
                        - updated_at
                        - watchlist_date
                        - watchlist_direction_code
                        - watchlist_direction_text
                        - watchlist_termination_date
                      type: object
                    type: array
                  next_cursor:
                    description: >-
                      Send as `cursor` to get the next page. `null` on the last
                      page, or when `limit` is 0.
                    nullable: true
                    type: string
                  total:
                    description: >-
                      Total number of results in the database that match the
                      query filters.
                    type: integer
                required:
                  - data
                  - next_cursor
                  - total
                title: MuniRatingsMoodysInstrumentsResponse
                type: object
          description: Moody's municipal instrument ratings
        '401':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Unauthorized
                          type: string
                        reason:
                          example: >-
                            Your account tier does not allow this operation.
                            Contact team@terrapinfinance.com for an upgrade.
                          type: string
                      required:
                        - detail
                      type: object
                    type: array
                required:
                  - errors
                type: object
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Payment Required
                          type: string
                        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
                      required:
                        - detail
                      type: object
                    type: array
                required:
                  - errors
                type: object
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Forbidden
                          type: string
                        reason:
                          example: >-
                            Your account tier does not allow this operation.
                            Contact team@terrapinfinance.com for an upgrade.
                          type: string
                      required:
                        - detail
                      type: object
                    type: array
                required:
                  - errors
                type: object
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        detail:
                          example: 'Invalid string. Got: integer'
                          type: string
                        source:
                          properties:
                            pointer:
                              example: /isins/0
                              type: string
                          required:
                            - pointer
                          type: object
                        title:
                          example: Invalid value
                          type: string
                      required:
                        - detail
                        - source
                        - title
                      type: object
                    type: array
                required:
                  - errors
                type: object
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Too Many Requests
                          type: string
                        reason:
                          type: string
                      required:
                        - detail
                      type: object
                    type: array
                required:
                  - errors
                type: object
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        detail:
                          example: Internal Server Error
                          type: string
                        reason:
                          type: string
                      required:
                        - detail
                      type: object
                    type: array
                required:
                  - errors
                type: object
          description: Internal Server Error
      callbacks: {}
components:
  securitySchemes:
    authorization:
      scheme: bearer
      type: http

````

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