Filtering & Pagination

Every tabular endpoint accepts the same shape of query parameters. Filters, sorting, pagination, and column selection are derived from the data catalog, so once you know the convention it applies to every model.

Filter operators

A filter is a query parameter named <field><Operator>. The field name is the model’s public field (as it appears in the response), and the operator is one of the suffixes below.

GET /query/tabular/assets?circulatingMarketcapGte=1000000000&symbolIsOneOf=BTC,ETH

There is no bare-field form, and ?symbol=BTC is rejected. Always include the operator suffix (?symbolEq=BTC). Any query parameter the endpoint does not recognize returns 400, so a typo fails loudly instead of silently returning unfiltered data.

Operator suffixes

Suffix	Meaning	Example
`Eq`	Equals	`?symbolEq=BTC`
`NotEq`	Does not equal	`?isStablecoinNotEq=true`
`Gt`	Greater than	`?circulatingMarketcapGt=1000000000`
`Gte`	Greater than or equal to	`?circulatingMarketcapGte=1000000000`
`Lt`	Less than	`?circulatingMarketcapRankLt=100`
`Lte`	Less than or equal to	`?circulatingMarketcapRankLte=100`
`IsOneOf`	Value is in the list	`?symbolIsOneOf=BTC,ETH,SOL`
`IsNotOneOf`	Value is not in the list	`?sectorIsNotOneOf=Stablecoins`
`Contains`	Case-insensitive substring match	`?nameContains=bit`
`Includes`	Array column contains this element	`?sectorsV2Includes=DeFi`
`NotIncludes`	Array column does not contain this element	`?sectorsV2NotIncludes=DeFi`
`IncludesAnyOf`	Array column contains at least one of these	`?sectorsV2IncludesAnyOf=DeFi,Layer1`
`NotIncludesAnyOf`	Array column contains none of these	`?sectorsV2NotIncludesAnyOf=DeFi,Layer1`

Multi-value operators (IsOneOf, IsNotOneOf, IncludesAnyOf, NotIncludesAnyOf) take a comma-separated list, and may also be repeated: ?symbolIsOneOf=BTC&symbolIsOneOf=ETH is equivalent to ?symbolIsOneOf=BTC,ETH.

Which operators a column supports

Not every column exposes every operator. The available set is constrained by the column’s type and declared per column in the catalog:

Column type	Available operators
String	`Eq`, `NotEq`, `IsOneOf`, `IsNotOneOf`, `Contains`
Numeric and time	`Eq`, `NotEq`, `Gt`, `Gte`, `Lt`, `Lte`, `IsOneOf`, `IsNotOneOf`
Boolean	`Eq`, `NotEq`
Array	`Includes`, `NotIncludes`, `IncludesAnyOf`, `NotIncludesAnyOf`

The catalog endpoints list the exact operators enabled for each column, and each endpoint’s reference page documents its full parameter list.

Combining filters

Multiple filters combine with AND.

GET /query/tabular/assets
  ?circulatingMarketcapGte=1000000000
  &circulatingMarketcapLte=5000000000
  &sectorIsOneOf=DeFi,Smart%20Contract%20Platform

Date and time values

Any filter on a time column accepts three formats:

RFC3339: 2026-07-13T00:00:00Z
Unix seconds: 1783843200
YYYY-MM-DD: 2026-07-13

Sorting

Parameter	Description
`sortBy`	Field to sort by. Restricted to the model’s sortable columns; defaults to the model’s default sort column.
`sortDirection`	`asc` (default) or `desc`.

GET /query/tabular/assets?sortBy=circulatingMarketcap&sortDirection=desc

Pagination

Parameter	Description
`page`	1-based page number.
`pageSize`	Rows per page. Defaults to `100`, maximum `1000`.

GET /query/tabular/assets?page=3&pageSize=250

The response’s metadata reports the totals for the full filtered result set, so you can size your loop before you start:

{
  "metadata": {
    "totalRows": 1482,
    "totalPages": 6
  }
}

totalRows and totalPages describe the whole filtered set, not the current page. Pair them with pageSize to know how many requests a full extract will take, or switch to CSV, which returns the page in a single downloadable file.

Selecting columns

selections takes a comma-separated list of field names and limits the response to those columns. It defaults to every field on the model, and it is supported on every endpoint, including the single-row endpoint. An unknown field name returns 400 with unknown selection field "...".

GET /query/tabular/assets?selections=assetID,name,symbol
GET /query/tabular/assets/bitcoin?selections=assetID,name,symbol

On timeseries endpoints, selections names the metric fields to return. A point always leads with its timestamp, and the remaining values are described by point_schema, so read the schema rather than assuming positions.

GET /query/timeseries/asset-price/1d/1e31218a-e44e-4285-820c-8282ee222035?selections=close,volume

Response formats

Every endpoint that returns array-like data supports three encodings. Set them with the acceptFormat query parameter, or with a standard Accept header.

`acceptFormat`	`Accept` header	Content type
`json` (default)	`application/json`	`application/json`
`csv`	`text/csv`	`text/csv; charset=utf-8`
`jsonl`	`application/x-ndjson`	`application/x-ndjson`

acceptFormat takes precedence over the Accept header when both are present.

csv and jsonl return the rows as a downloadable file: the response carries a Content-Disposition: attachment header and is not wrapped in the error/data envelope. Use them for extracts and spreadsheet workflows; use JSON for application code.

curl 'https://api.blockworks.com/query/tabular/assets?pageSize=1000&acceptFormat=csv' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --output assets.csv

curl 'https://api.blockworks.com/query/tabular/assets?pageSize=1000' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/x-ndjson' \
  --output assets.jsonl

Full example

curl -G 'https://api.blockworks.com/query/tabular/assets' \
  --header 'X-Blockworks-API-Key: YOUR_API_KEY' \
  --data-urlencode 'circulatingMarketcapGte=1000000000' \
  --data-urlencode 'sortBy=circulatingMarketcap' \
  --data-urlencode 'sortDirection=desc' \
  --data-urlencode 'selections=assetID,name,symbol,circulatingMarketcap' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=50'

Getting Started

Discovery

Concepts

Market Data

Blockchains

Projects & Protocols

Real World Assets

Institutional

Fundraising

Social & Mindshare

News & Research

Token Transparency Framework

Charts

Filter operators

Operator suffixes

Which operators a column supports

Combining filters

Date and time values

Sorting

Selecting columns

Response formats

Full example

​Filter operators

​Operator suffixes

​Which operators a column supports

​Combining filters

​Date and time values

​Sorting

​Pagination

​Selecting columns

​Response formats

​Full example

Filter operators

Operator suffixes

Which operators a column supports

Combining filters

Date and time values

Sorting

Pagination

Selecting columns

Response formats

Full example