Querying Art Blocks Data#

When to Use GraphQL vs Domain Tools#

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

NeedToolBrowse/search projectsdiscover_projectsFull project detailsget_projectArtist's body of workget_artistPortfolio overviewget_wallet_summaryCollector's tokensget_wallet_tokensToken detailsget_token_metadataLive mintsdiscover_live_mintsUpcoming dropsdiscover_upcoming_releasesMint eligibilitycheck_allowlist_eligibility

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.

ParamRequiredNotestableNameyesTable to exploreshowAllFields—true for full schema dump (default: curated shortlist)

Preferred Tables#

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

Use thisNot thisprojects_metadata``projects``tokens_metadata``tokens``contracts_metadata``contracts

query_optimizer will automatically rewrite queries that use the wrong table.

Chain IDs#

ChainIDEthereum mainnet1 (default)Arbitrum42161Base8453

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)#

graphql

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#

graphql

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)#

graphql

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#

graphql

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