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

# S&P Instrument Ratings

> Requires an existing license with S&P.

Pass `isins` for the live 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.

S&P deletes actions as well as issuing them. With `updated_since`, deleted
actions are returned too, with `is_deleted` true, so an incremental pull
can drop them.


> [!WARNING]
>
> Access requires an existing license with S\&P.


## OpenAPI

````yaml post /api/v1/muni_ratings_snp_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_snp_instruments:
    post:
      tags: []
      summary: S&P municipal bond instrument ratings
      description: >
        Requires an existing license with S&P.


        Pass `isins` for the live 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.


        S&P deletes actions as well as issuing them. With `updated_since`,
        deleted

        actions are returned too, with `is_deleted` true, so an incremental pull

        can drop them.
      operationId: post_muni_ratings_snp_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:
                      - '-creditwatch'
                      - '-creditwatch_date'
                      - '-current_rating_symbol'
                      - '-cusip'
                      - '-cwol_action_word'
                      - '-cwol_ind'
                      - '-is_deleted'
                      - '-maturity_date'
                      - '-org_debt_type_code'
                      - '-outlook'
                      - '-outlook_date'
                      - '-prior_creditwatch'
                      - '-prior_outlook'
                      - '-prior_rating_symbol'
                      - '-rating_action_word'
                      - '-rating_date'
                      - '-rating_detail_id'
                      - '-rating_qualifier'
                      - '-rating_symbol'
                      - '-rating_type_code'
                      - '-regulatory_indicator'
                      - '-regulatory_qualifier'
                      - '-updated_at'
                      - creditwatch
                      - creditwatch_date
                      - current_rating_symbol
                      - cusip
                      - cwol_action_word
                      - cwol_ind
                      - is_deleted
                      - maturity_date
                      - org_debt_type_code
                      - outlook
                      - outlook_date
                      - prior_creditwatch
                      - prior_outlook
                      - prior_rating_symbol
                      - rating_action_word
                      - rating_date
                      - rating_detail_id
                      - rating_qualifier
                      - rating_symbol
                      - rating_type_code
                      - regulatory_indicator
                      - regulatory_qualifier
                      - updated_at
                    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 `rating_detail_id`: 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:
                  - creditwatch: null
                    creditwatch_date: null
                    current_rating_symbol: AA-
                    cusip: 1966324Q3
                    cwol_action_word: null
                    cwol_ind: null
                    is_deleted: false
                    isin: US1966324Q32
                    maturity_date: '2035-02-01T00:00:00Z'
                    org_debt_type_code: null
                    outlook: Stable
                    outlook_date: '2026-08-01T00:00:00Z'
                    prior_creditwatch: null
                    prior_outlook: Positive
                    prior_rating_symbol: A+
                    rating_action_word: Upgrade
                    rating_date: '2026-08-01T00:00:00Z'
                    rating_detail_id: 12345
                    rating_qualifier: null
                    rating_symbol: AA-
                    rating_type_code: STDLONG
                    regulatory_indicator: null
                    regulatory_qualifier: null
                    updated_at: '2026-08-01T12:00:00Z'
                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:
                        creditwatch:
                          description: CreditWatch status at the time of the action.
                          nullable: true
                          type: string
                        creditwatch_date:
                          description: >-
                            Datetime the CreditWatch status was set, in UTC.
                            This is a datetime and not a date because that is
                            how S&P reports it.
                          format: date-time
                          nullable: true
                          type: string
                        current_rating_symbol:
                          description: >-
                            Rating symbol this action leaves on its line, e.g.
                            `AA-`.
                          example: AA-
                          nullable: true
                          type: string
                        cusip:
                          description: CUSIP of the rated municipal security.
                          example: 1966324Q3
                          nullable: true
                          type: string
                        cwol_action_word:
                          description: CreditWatch / outlook action word, if any.
                          nullable: true
                          type: string
                        cwol_ind:
                          description: CreditWatch / outlook indicator, if any.
                          nullable: true
                          type: string
                        is_deleted:
                          description: >-
                            Whether S&P deleted this action. Deleted actions 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
                        maturity_date:
                          description: >-
                            Maturity date of the rated instrument, in UTC. This
                            is a datetime and not a date because that is how S&P
                            reports it.
                          format: date-time
                          nullable: true
                          type: string
                        org_debt_type_code:
                          description: S&P organization debt-type code.
                          nullable: true
                          type: string
                        outlook:
                          description: Outlook at the time of the action.
                          nullable: true
                          type: string
                        outlook_date:
                          description: >-
                            Datetime the outlook was set, in UTC. This is a
                            datetime and not a date because that is how S&P
                            reports it.
                          format: date-time
                          nullable: true
                          type: string
                        prior_creditwatch:
                          description: CreditWatch status before this action.
                          nullable: true
                          type: string
                        prior_outlook:
                          description: Outlook before this action.
                          nullable: true
                          type: string
                        prior_rating_symbol:
                          description: Rating symbol before this action.
                          example: A+
                          nullable: true
                          type: string
                        rating_action_word:
                          description: >-
                            Action taken, e.g. `Upgrade`, `Downgrade`,
                            `Affirmed`.
                          example: Upgrade
                          nullable: true
                          type: string
                        rating_date:
                          description: >-
                            Datetime of the rating action, in UTC. This is a
                            datetime and not a date because that is how S&P
                            reports it.
                          format: date-time
                          nullable: false
                          type: string
                        rating_detail_id:
                          description: >-
                            S&P rating-detail identifier. Stable across updates
                            to this action.
                          example: 12345
                          nullable: false
                          type: integer
                        rating_qualifier:
                          description: S&P rating qualifier, if any.
                          nullable: true
                          type: string
                        rating_symbol:
                          description: S&P rating symbol as reported on the action.
                          example: AA-
                          nullable: true
                          type: string
                        rating_type_code:
                          description: >-
                            S&P rating line, e.g. `STDLONG` (long-term),
                            `STDSHORT` (short-term), `SPUR` (underlying).
                          example: STDLONG
                          nullable: true
                          type: string
                        regulatory_indicator:
                          description: S&P regulatory indicator, if any.
                          nullable: true
                          type: string
                        regulatory_qualifier:
                          description: S&P regulatory qualifier, if any.
                          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
                      required:
                        - creditwatch
                        - creditwatch_date
                        - current_rating_symbol
                        - cusip
                        - cwol_action_word
                        - cwol_ind
                        - is_deleted
                        - isin
                        - maturity_date
                        - org_debt_type_code
                        - outlook
                        - outlook_date
                        - prior_creditwatch
                        - prior_outlook
                        - prior_rating_symbol
                        - rating_action_word
                        - rating_date
                        - rating_detail_id
                        - rating_qualifier
                        - rating_symbol
                        - rating_type_code
                        - regulatory_indicator
                        - regulatory_qualifier
                        - updated_at
                      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: MuniRatingsSnpInstrumentsResponse
                type: object
          description: S&P 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.