Search & Filter Objects

Use Dual's search API to query, filter, and paginate across large object collections.

What You'll Build

As your token library grows, you'll need efficient ways to find objects. Dual provides powerful search and filter capabilities, by template, owner, properties, and more. In this tutorial you'll master the object query API with pagination, sorting, and aggregation.

Step 1, Basic Object Listing

Start with a simple paginated list of your objects:

bash
curl "https://api-testnet.dual.network/objects?limit=10" \\

  -H "Authorization: Bearer $DUAL_TOKEN"

The response includes a results array and a next cursor for pagination. Pass ?next=CURSOR_VALUE to fetch the next page.

Step 2, Filter by Template

Retrieve only objects minted from a specific template:

bash
curl "https://api-testnet.dual.network/objects?template_id=your-template-id&limit=20" \\

  -H "Authorization: Bearer $DUAL_TOKEN"

Step 3, Search by Properties

Use the search endpoint to find objects by their custom properties:

bash
curl -X POST https://api-testnet.dual.network/objects/search \\

  -H "Authorization: Bearer $DUAL_TOKEN" \\

  -H "Content-Type: application/json" \\

  -d '{

    "filters": {

"template_id": "my-org::loyalty-card::v1",

"properties.tier": "gold",

"properties.points": { "$gte": 500 }

    },

    "sort": { "properties.points": -1 },

    "limit": 50

  }'

Supported filter operators:

Step 4, Count Objects

Get a quick count without fetching full objects, useful for dashboards:

bash
curl -X POST https://api-testnet.dual.network/objects/count \\

  -H "Authorization: Bearer $DUAL_TOKEN" \\

  -H "Content-Type: application/json" \\

  -d '{

    "filters": {

"template_id": "my-org::loyalty-card::v1",

"properties.redeemed": false

    }

  }'

Step 5, Navigate Object Hierarchies

Objects can have parent-child relationships. Query the hierarchy:

bash
# Get children of an object

curl "https://api-testnet.dual.network/objects/{objectId}/children" \\

  -H "Authorization: Bearer $DUAL_TOKEN"



# Get parents of an object

curl "https://api-testnet.dual.network/objects/{objectId}/parents" \\

  -H "Authorization: Bearer $DUAL_TOKEN"

Performance Tip: Always include a template_id filter when searching large datasets. This lets Dual use indexed lookups instead of full scans.

What's Next?

Ready to go public? Try Querying the Public API to build read-only interfaces without authentication.

What You'll BuildStep 1, Basic Object ListingStep 2, Filter by TemplateStep 3, Search by PropertiesStep 4, Count ObjectsStep 5, Navigate Object HierarchiesWhat's Next?