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

> Get unspent transaction outputs containing a specific Bitcoin Rune token with amounts and holder information.

# UTxOs by Runes



## OpenAPI

````yaml bitcoin/blockchain-indexer-api/openapi.json get /assets/runes/{rune}/utxos
openapi: 3.0.3
info:
  title: Bitcoin - Blockchain Indexer API
  description: >-
    This API provides core indexer endpoints with support for Bitcoin
    metaprotocols by delivering real-time, rollback-protected access to
    Bitcoin's UTXO data, enabling developers to build responsive and reliable
    blockchain applications without managing complex infrastructure.


    #### Key Features:

    - **Real-Time Data with Rollback Protection:** Ensures data accuracy by
    handling chain reorganizations gracefully, providing live data without
    sacrificing integrity.

    - **Comprehensive UTXO Indexing:** Specialized pipelines extract, match, and
    process on-chain information, including handling rollbacks, to provide
    accurate and up-to-date data.


    #### Key Benefits for Developers:

    By abstracting the complexities of blockchain data retrieval and processing,
    Maestro's Bitcoin Indexer API empowers developers to focus on building
    innovative applications with confidence in fast and reliable access to
    historical chain data.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  version: v0.2.0
servers:
  - url: https://xbt-mainnet.gomaestro-api.org/v0
    description: Bitcoin Mainnet
  - url: https://xbt-testnet.gomaestro-api.org/v0
    description: Bitcoin Testnet
security:
  - api-key: []
paths:
  /assets/runes/{rune}/utxos:
    get:
      tags:
        - Runes
      summary: UTxOs by Runes
      description: >-
        Returns all UTXOs containing the specified Rune. Useful for raw state
        tracking and detailed token flow visualization.
      operationId: utxos_by_rune
      parameters:
        - name: rune
          in: path
          description: >-
            Rune, specified either by the Rune ID (etching block number and
            transaction index) or name (spaced or un-spaced)
          required: true
          schema:
            type: string
          example: '2519999:31'
        - name: count
          in: query
          description: The max number of results per page
          required: false
          schema:
            allOf:
              - type: integer
                default: 100
                minimum: 0
            nullable: true
        - name: order
          in: query
          description: >-
            The order in which the results are sorted (by height at which UTxO
            was produced)
          required: false
          schema:
            allOf:
              - type: string
                default: asc
                enum:
                  - asc
                  - desc
            nullable: true
        - name: from
          in: query
          description: Return only UTxOs created on or after a specific height
          required: false
          schema:
            type: integer
            format: int64
            nullable: true
            minimum: 0
        - name: to
          in: query
          description: Return only UTxOs created on or before a specific height
          required: false
          schema:
            type: integer
            format: int64
            nullable: true
            minimum: 0
        - name: cursor
          in: query
          description: >-
            Pagination cursor string, use the cursor included in a page of
            results to fetch the next page
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Requested data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRuneUtxo'
              example:
                data:
                  - address: bc1ql8k89mfzqwjaqnq0y9uxummllp6v92fkykkv78
                    confirmations: 50
                    height: 840001
                    rune_amount: '1.00'
                    satoshis: '546'
                    script_pubkey: 0014f9ec72ed2203a5d04c0f21786e6f7ff874c2a936
                    txid: >-
                      fa2fa7ea017e9e8eaf701b26bb57c0ed3f550428b59df17bd789ad98f6bf5a2b
                    vout: 0
                  - address: bc1qdkzx0dnzuyzjlu7qk86mc7rgkpwwms6zg5y5gd
                    confirmations: 50
                    height: 840001
                    rune_amount: '1.00'
                    satoshis: '546'
                    script_pubkey: 00146d8467b662e1052ff3c0b1f5bc7868b05cedc342
                    txid: >-
                      452378b6ef2bd45dbd1bada84b9468b57fcccbfef67777dfb99f5e8f3a7cfd80
                    vout: 0
                last_updated:
                  block_hash: >-
                    00000000000000000001332b3017e2b72bdd063145bbf808b3c1722a0fd60859
                  block_height: 840051
                next_cursor: AAAAAAAM0UFggP18Oo9en7nfd3f2_svMf7VolEuorRu9XdQr77Z4I0VgAAAAAA
        '400':
          description: Malformed query parameters
        '404':
          description: Requested entity not found on-chain
        '500':
          description: Internal server error
components:
  schemas:
    PaginatedRuneUtxo:
      type: object
      required:
        - data
        - last_updated
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RuneUtxo'
        last_updated:
          $ref: '#/components/schemas/ChainTip'
        next_cursor:
          type: string
          nullable: true
    RuneUtxo:
      type: object
      required:
        - txid
        - vout
        - script_pubkey
        - satoshis
        - confirmations
        - height
        - rune_amount
      properties:
        address:
          type: string
          nullable: true
        confirmations:
          type: integer
          format: int64
          minimum: 0
        height:
          type: integer
          format: int64
          minimum: 0
        rune_amount:
          type: string
        satoshis:
          type: string
        script_pubkey:
          type: string
        txid:
          type: string
        vout:
          type: integer
          format: int32
          minimum: 0
    ChainTip:
      type: object
      required:
        - block_hash
        - block_height
      properties:
        block_hash:
          type: string
          description: The hash of the block
          example: 0000000000000000000a7f3b7b6b6e1d9a18db65a3b4a3f4f3bcb2e1f1b2d3e7
        block_height:
          type: integer
          format: int64
          description: The height of the block in the blockchain
          example: 707000
          minimum: 0
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key
      description: Project API Key

````