metadataList

The metadataList query retrieves a paginated list of NFT metadata records with comprehensive filtering, sorting, and pagination capabilities.

It returns a MetadataList object containing an array of Metadata objects with detailed metadata information including names, descriptions, attributes, external URLs, and timing information.

Schema Definition

metadataList(
  first: Int = 10
  skip: Int = 0
  where: MetadataFilter
  orderBy: MetadataOrderBy
  orderDirection: Ordering
): MetadataList!

Arguments

Argument	Type	Description
first	Int = 10 scalar	Maximum number of metadata records to retrieve per page. Maximum value is 100.
skip	Int = 0 scalar	Number of metadata records to bypass before assembling the page. Set to the first value from the previous page for offset pagination.
where	MetadataFilter input	Specifies subsets of metadata to be retrieved.
orderBy	MetadataOrderBy enum	Sets how the list of metadata records is ordered.
orderDirection	Ordering enum	Sets the direction in which the list of metadata records is ordered.

Return Type

MetadataList object

Common Use Cases

• Analyze metadata quality and completeness for collections by examining attribute distributions and missing fields.
• Track metadata updates and changes over time using timestamp filters (createdAtGte/createdAtLte or updatedAtGte/updatedAtLte).
• Build bulk metadata analysis tools for collection management, trait rarity calculations, or metadata standardization efforts.
• Generate collection reports analyzing trait distributions, attribute completeness, and metadata patterns across large NFT sets.
• Create metadata dashboards showing recently added or updated NFTs within specific time periods.

Example

Query

Analyze Recently Updated Collection Metadata

query AnalyzeCollectionMetadata($where: MetadataFilter, $first: Int, $orderBy: MetadataOrderBy, $orderDirection: Ordering) {
  metadataList(
    where: $where
    first: $first
    orderBy: $orderBy
    orderDirection: $orderDirection
  ) {
    numEntries
    cursor
    entries {
      name
      description
      updatedAt
      createdAt
      tokenURI
      externalUrl
      attributes {
        traitType
        value
        displayType
      }
    }
  }
}

Variables

{
  "where": {
    "updatedAtGte": "2025-01-01T00:00:00Z",
    "updatedAtLte": "2025-01-31T23:59:59Z"
  },
  "first": 50,
  "orderBy": "UPDATED_AT",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "metadataList": {
      "numEntries": 50,
      "cursor": 1234567890,
      "entries": [
        {
          "name": "Bored Ape #5234",
          "description": "A unique Bored Ape Yacht Club NFT",
          "updatedAt": "2025-01-28T14:32:18Z",
          "createdAt": "2023-05-15T10:22:45Z",
          "tokenURI": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/5234",
          "externalUrl": "https://boredapeyachtclub.com/#/gallery/5234",
          "attributes": [
            {
              "traitType": "Background",
              "value": "Orange",
              "displayType": null
            },
            {
              "traitType": "Fur",
              "value": "Brown",
              "displayType": null
            },
            {
              "traitType": "Eyes",
              "value": "Bored",
              "displayType": null
            }
          ]
        }
      ]
    }
  }
}

Implementation Notes

note

• The default first value is 10 transactions. OneSource enforces a maximum first value of 100. Adjust based on your UI needs.
• Use skip for offset-based pagination. To get the next page, use a skip value equal to the previous first value.
• All range filters use Gte (greater than or equal to) and Lte (less than or equal to) suffixes for inclusive ranges.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.