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

flowchart TB
    subgraph c["Collection: /v2/packages/active"]
        direction LR
        C1["1 request<br/>to T3"] --> C2["1 request<br/>to Metrc"] --> C3["Packages,<br/>no metadata"] --> C4["Fast, generous<br/>rate limit"]
    end
    subgraph s["Supercollection: /v2/packages/active/super?include=labResults"]
        direction LR
        S1["1 request<br/>to T3"] --> S2["1 request for the packages,<br/>then 1 per package<br/>for its lab results"] --> S3["labResults attached<br/>and metadata<br/>fields populated"] --> S4["Slower, lower<br/>rate limit"]
    end

What is a Supercollection?¶

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

• T3 collection endpoints 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, 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¶

The tag, tag order, location and strain rows have no include options: there is no related Metrc data to attach to a tag, tag order, location or strain. They exist as /super paths so that a caller building URLs by pattern does not have to special-case them, and they return the same records their plain collection counterparts do.

A tag order's details line items are the one thing that might look like an include but is not: Metrc returns them embedded in the order itself, so they are present on the plain collection too.

GET https://api.trackandtrace.tools/v2/tagorders/history/super?licenseNumber=LIC000001

{
  "orderNumber": "SBX-MO-2026-035-0594",
  "statusName": "Received",
  "details": [
    { "tagType": "CannabisPackage", "quantity": 26, "unitPrice": 0.46 },
    { "tagType": "CannabisPlant", "quantity": 56, "unitPrice": 0.46 }
  ],
  "metadata": {
    "summary": "SBX-MO-2026-035-0594 · Received · 82 tags",
    "description": "Tag order SBX-MO-2026-035-0594. Status: Received. Ordered: 82 tags."
  }
}

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_number = pick_license(api_client=api_client)

    all_packages = load_all_data_sync(
        client=api_client,
        path="/v2/packages/active/super",
        license_number=license_number["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, indexedLabResults, plus the unconditional netWeightOrVolume / netWeightOrVolumeUnitOfMeasure.

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

Next Steps¶

• Every include, per collection: Supercollection Includes.
• Hydrate a single record instead of a page: Loading One Record by ID.
• Export a whole supercollection at once with Super Reports.
• Find records to load with Search.