Filtering & pagination.

Compose metric filters#

A filter group has an AND or OR operator and an array of conditions. Each condition compares a metric to a number. Nest groups when you need more expressive criteria.

{
  "metrics": [
    "volume",
    "liquidity",
    "price"
  ],
  "filters": {
    "operator": "AND",
    "conditions": [
      {
        "metric": "volume",
        "operator": "gte",
        "value": 100000
      },
      {
        "metric": "price",
        "operator": "lt",
        "value": 0.9
      }
    ]
  },
  "tags_any": [
    "crypto",
    "economics"
  ],
  "sort": {
    "metric": "volume",
    "direction": "desc"
  },
  "pagination": {
    "limit": 20
  }
}

gt / gteComparison

Greater than / greater than or equal to.

lt / lteComparison

Less than / less than or equal to.

eq / neqComparison

Equal to / not equal to.

tags_any / tags_all / tags_nonestring[]

Match any, require all, or exclude the specified lowercase tag slugs. Up to 50 tags per list.

price_min / price_maxnumber

Inclusive probability bounds from 0 to 1. The minimum must not exceed the maximum.

Work with time windows#

Supported windows are 5m, 15m, 30m, 1h, 4h, 24h, 7d, and 30d. Use delta_abs for a numeric change or delta_pct for the relative percentage change. Supply window and compare together when filtering or sorting by a delta.

A requested delta can use either a fixed window or an ISO-8601 since timestamp, but not both. Up to 10 deltas can be requested, including up to five since-based deltas within the last 30 days.

Paginate with cursors#

Discovery uses cursor pagination with a default page size of 20 and a maximum of 100. Treat the returned next_cursor as an opaque string and send it unchanged. Cursors are tied to the current sort; start a new query after changing your filters or ordering.

Other endpoint families may use offset pagination. Read each endpoint’s parameters instead of applying discovery cursors across the API.

{
  "metrics": ["volume", "liquidity", "price"],
  "sort": { "metric": "volume", "direction": "desc" },
  "pagination": {
    "limit": 20,
    "cursor": "<next_cursor from the previous response>"
  }
}

Handle incomplete history#

Use nulls: "last" to place unavailable deltas after valid results, or nulls: "exclude" to omit them. The "zero" policy is available only for absolute delta comparisons. A missing value should not be displayed as a measured zero.

okDelta status

The requested comparison value is available.

too_newDelta status

The market is younger than the requested window.

missing_historyDelta status

The market is old enough, but the historical value is unavailable.

div0Delta status

A percentage delta cannot be computed because the historical base is zero.