Docs

Search & Filter Objects

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

10 minBeginner

Prerequisites

  • A DUAL account with minted objects
  • Familiarity with query parameters

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://blockv-labs.io/objects?limit=10&offset=0" \
  -H "Authorization: Bearer $DUAL_TOKEN"

The response includes a results array and pagination metadata (total, limit, offset).

Step 2 — Filter by Template

Retrieve only objects minted from a specific template:

bash
curl "https://blockv-labs.io/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://blockv-labs.io/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:

OperatorDescriptionExample
$eqEqual to{"tier": {"$eq": "gold"}}
$gteGreater than or equal{"points": {"$gte": 100}}
$lteLess than or equal{"points": {"$lte": 1000}}
$inIn array{"tier": {"$in": ["gold","platinum"]}}
$existsField exists{"redeemed_at": {"$exists": true}}

Step 4 — Count Objects

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

bash
curl -X POST https://blockv-labs.io/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://blockv-labs.io/objects/{objectId}/children" \
  -H "Authorization: Bearer $DUAL_TOKEN"

# Get parents of an object
curl "https://blockv-labs.io/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.

Organization Roles & PermissionsQuerying the Public API