Querying Art Blocks Data

When to Use GraphQL vs Domain Tools

The domain-specific tools cover most use cases and are easier to use:

Use the GraphQL tools below as an escape hatch for custom queries not covered above — sales history, aggregations, complex joins, or tables without a dedicated tool.

Resource: artblocks://about

Fetch this resource for platform context — vocabulary, verticals, chains, tags, user profiles, and a guide to which tool handles what.

Tool Hierarchy

Use tools in this order — skip steps you don't need:

1. Discover schema → explore_table (single table with fields + relationships) or graphql_introspection (full schema)
2. Build a validated query → build_query (validates fields, adds suggestions, auto-filters by chain)
3. Optimize → query_optimizer (rewrites to preferred tables, e.g. projects_metadata over projects)
4. Execute → graphql_query

If you already know the schema, go straight to build_query → graphql_query.

Tool: explore_table

For well-known tables (projects_metadata, tokens_metadata), returns a curated shortlist of the most useful fields organized by category (Identity, Status, Media, Market, etc.) plus key relationships with suggested subfields. Pass showAllFields: true to see the full schema dump instead.

Preferred Tables

Always use the _metadata variants — they include richer joined data:

query_optimizer will automatically rewrite queries that use the wrong table.

Chain IDs

Pass chainId to graphql_query to make $chainId available as a variable in your query.

Common Query Patterns

These examples show queries that require raw GraphQL — things the domain tools can't do.

Recent sales (no domain tool covers purchases)

query {
  purchases_metadata(
    order_by: { block_timestamp: desc }
    limit: 20
    where: { chain_id: { _eq: 1 } }
  ) {
    token_id
    price_in_eth
    block_timestamp
    buyer_address
    seller_address
  }
}

Aggregate token count by owner for a project

query {
  tokens_metadata_aggregate(
    where: { project_id: { _eq: "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-78" } }
    distinct_on: owner_address
  ) {
    aggregate { count }
  }
}

All tokens for a project (domain tools only return per-wallet)

query {
  tokens_metadata(
    where: { project_id: { _eq: "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-0" } }
    order_by: { invocation: asc }
    limit: 50
  ) {
    token_id
    invocation
    owner_address
    features
  }
}

Projects with specific on-chain attributes

query {
  projects_metadata(
    where: {
      script_type_and_version: { _ilike: "%three%" }
      chain_id: { _eq: 1 }
      complete: { _eq: false }
    }
    limit: 20
  ) {
    id
    name
    artist_name
    script_type_and_version
    invocations
    max_invocations
  }
}

Tips

• Use explore_table to understand fields and relationships before writing a query — the curated view is much easier to scan than the full schema dump
• build_query is the safest way to start — it validates fields and tells you what's available
• Always pass chainId when querying multi-chain data to avoid cross-chain noise
• For unknown fields, validate_fields is faster than a full introspection