Conventions

Pagination, filtering, ordering, scalar formats, historical data, and indexing health.

The same shape applies to every paginated query in the API. Once you've used one, the others read the same way.

The schema is the source of truth. This page documents conventions, not every field. For exhaustive type and field listings, use Apollo Sandbox — introspection is enabled.

Pagination

All list queries are offset-paginated with two required arguments:

Argument	Type	Description
first	Int!	Page size. Keep ≤ 100.
skip	Int!	Offset from the start of the result set.

The response is wrapped in a Page type — for example VaultPage, TransactionPage, UserPage — with two fields:

Field	Type	Description
items	[Entity!]!	The current page of entities.
pageInfo	PageInfo!	Pagination metadata.

PageInfo exposes count, limit, skip, totalCount, hasNextPage, hasPreviousPage. Always request pageInfo { hasNextPage totalCount } if you need to know when to stop.

Filtering

Each list query accepts a typed where: EntityFilterInput. Filter fields follow a <field>_<op> naming convention:

Suffix	Meaning	Example
_eq	equals	chainId_eq: 1
_not_eq	not equals	state_not_eq: Closed
_in	in array	address_in: ["0x…", "0x…"]
_not_in	not in array	chainId_not_in: [137, 10]
_contains	array contains value	curatorIds_contains: "0x…"
_contains_any	array contains any of	curatorIds_contains_any: ["0x…", "0x…"]
_gt / _gte / _lt / _lte	numeric / timestamp comparison	timestamp_gt: 1780000000

Not every field on every entity supports every operator — Apollo Sandbox lists exactly which <field>_<op> keys exist per filter input.

Example: visible Ethereum vaults with a specific symbol whitelist:

query FilterExample {
  vaults(
    first: 50
    skip: 0
    orderBy: totalAssetsUsd
    orderDirection: desc
    where: {
      chainId_eq: 1
      isVisible_eq: true
      symbol_in: ["T9cbBTC", "T9USDC"]
    }
  ) {
    items { address name symbol }
  }
}

Try in Apollo Sandbox →

Ordering

Two arguments, both with safe defaults:

Argument	Type	Description
orderBy	<Entity>OrderBy!	Typed enum, per-entity. For example VaultOrderBy.totalAssetsUsd, TransactionOrderBy.timestamp.
orderDirection	OrderDirection	asc or desc. Defaults to asc.

Scalars

Scalar	Format	Notes
Address	0x-prefixed lowercase hex string	Returned lowercase; accepted in either case.
BigInt	Decimal string	Used for token amounts, block numbers, Unix timestamps, basis points. JSON-safe.
HexString	0x-prefixed hex string	Transaction hashes, block hashes.
JSONObject	Arbitrary JSON object	Free-form metadata.
Float	IEEE-754 double	USD values, APRs, percentages.
Timestamps	Unix seconds, as Float or BigInt	Not milliseconds.

Historical data

Every vault exposes its own history without a separate query:

vault.stateAt(timestamp: Int!)

Point-in-time reconstruction of the vault from indexed onchain history. Returns a HistoricalVaultState with the same metric fields as state (totalAssets, pricePerShare, fees, roles, access mode, guardrails, APRs, …). Returns null (or BAD_USER_INPUT) for timestamps before the vault's first state row.

vault.stateHistory

Time series of every field in state that has a recorded history (price per share, total assets, supply, fees, etc.). Each field returns an ascending list of data points within an optional TimeRangeOptions window (default: from vault creation to now). Capped at the 1000 most recent events per underlying table — for full backfills, page through transactions directly.

stateHistory is the building block for rolling your own APR or PnL — see APR computations for the formulas used by the indexer.

Request limits

Limit	If exceeded
Query depth	Restructure into shallower queries.
Max complexity	Trim fields from the selection set, or lower first.
Rate limit	You'll receive HTTP 429. Back off and retry with exponential backoff; contact the Lagoon team if you need a higher limit.

Indexing health

_meta.lastIndexedBlocks returns the most recent block per chain that produced a tracked event. Pass chainIds to scope the response:

query IndexingHealth {
  _meta(chainIds: [1, 8453]) {
    lastIndexedBlocks {
      chainId
      number
      hash
      chain { name }
    }
  }
}

Try in Apollo Sandbox →

This value can trail the chain head on low-activity chains, but lag is bounded to ~1 hour. If a chain reports a number more than ~1 hour behind, treat its data as stale.