T3 API : Supercollections

Important

This wiki is migrating to wiki.trackandtrace.tools. Please visit the new site for the latest documentation.

• T3 API Supercollections
  • What is a Supercollection?
  • Available Supercollection Endpoints
  • The include Parameter
  • Superpackages Example
• Next Steps

---

T3 API Supercollections

With Metrc data, users frequently encounter these sorts of problems:

• "I want to load my packages, but also need test results for each"
• "I want to load my transfers, but also want all the packages"
• "I want to load my items, but I also want all the images and ingredients"

Enter supercollections

What is a Supercollection?

The best way to understand supercollections is to compare them to T3 collections:

• T3 collection endpoints all are designed to send exactly one request to Metrc per request to T3.
  • Examples: Active Packages, Incoming Transfers, Active Items.
  • This ensures the endpoints are fast, have generous rate limits, and are flexible to use.
  • If you want to load metadata for a collection, you need to explicitly request it per row.
• T3 supercollection endpoints are designed to eagerly load all metadata for each collection object.
  • Examples: Active Superpackages, Incoming Supertransfers, Active Superitems
  • They extend existing collection endpoint behavior.
  • This allows the endpoint to efficiently load, organize, and analyze the metadata for you.
  • Endpoints have lower rate limits, and are slower to use.
  • Metadata is loaded declaratively. For example, you'd specify you want lab results and history for an active superpackages request.

Available Supercollection Endpoints

Supercollection	Path	include options
Superitems	/v2/items/super	notes, history, ingredients, images
Active Superpackages	/v2/packages/active/super	labResults, labResultBatches, sourceHarvests, history
Inactive Superpackages	/v2/packages/inactive/super	labResults, labResultBatches, sourceHarvests, history
In Transit Superpackages	/v2/packages/intransit/super	labResults, labResultBatches, sourceHarvests, history
Incoming Active Supertransfers	/v2/transfers/incoming/active/super	packages, transporters
Outgoing Active Supertransfers	/v2/transfers/outgoing/active/super	packages, transporters

The include Parameter

The include parameter controls which additional data is fetched and attached to each object in the response. Without it, a supercollection request behaves like a regular collection request.

Each include value does two things:

1. Attaches raw Metrc data as a new array on each object (e.g. labResults, sourceHarvests)
2. Populates a metadata object with extracted, cleaned-up values derived from that raw data

For example, when requesting superpackages with include=labResults:

• Each package gains a labResults array containing the raw lab result records from Metrc
• Each package's metadata object is populated with:
  • extractedLabResults - parsed lab result values with tags
  • testSamplePackageLabels - deduplicated test sample labels
  • labResultPdfs - URLs to download lab result PDFs
  • indexedLabResults - a simplified dictionary for easy access (e.g. metadata.indexedLabResults.totalThc.value)

You can specify multiple include values to combine them: include=labResults&include=sourceHarvests

Superpackages Example

This is the most commonly used supercollection. Below is an example that loads all active superpackages with lab results for packages in the "Buds" product category:

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.8"
# dependencies = [
#     "t3api_utils",
# ]
# ///


from t3api_utils.api.parallel import load_all_data_sync
from t3api_utils.main.utils import (get_authenticated_client_or_error,
                                    interactive_collection_handler,
                                    pick_license)


def main():
    api_client = get_authenticated_client_or_error()

    license = pick_license(api_client=api_client)

    all_packages = load_all_data_sync(
        client=api_client,
        path="/v2/packages/active/super",
        license_number=license["licenseNumber"],
        page_size=50,
        include="labResults",
        filter="item.productCategoryName__eq:Buds"
    )

    interactive_collection_handler(data=all_packages)

if __name__ == "__main__":
    main()

Each object in the response will contain:

• All the standard package fields (label, item, quantity, etc.)
• A labResults array with the raw Metrc lab result data
• A metadata object with extractedLabResults, testSamplePackageLabels, labResultPdfs, and indexedLabResults

You can find more supercollection examples in the T3 API examples repository.

---

Next Steps

• Refer to the T3 API documentation to explore all the available endpoints.
• Most API endpoints require a T3+ subscription. If you don't have a T3+ subscription, you can sign up here.