> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# onFilterTokensUpdated

> Live-streamed updates for an active filterTokens result set. Polls every updatePeriod ms (default 500, max 60000).

<Note>
  Subscriptions use `wss://graphql.mobula.io/graphql` with the `graphql-transport-ws` protocol. `wss://graphql.mobula.io/graphql/subscriptions` is also supported for backwards compatibility.
</Note>

### Overview

Stream the current page of a [filterTokens](/api-reference/graphql/queries/filterTokens) query in real time. The same filters, rankings, and pagination arguments accepted by `filterTokens` are accepted here — the server re-evaluates them on every tick and pushes the full current page.

* First message is the full filtered set for the supplied arguments.
* Subsequent messages re-run the filter every `updatePeriod` ms and yield the full current set (not a delta).
* `updatePeriod` defaults to 500 ms and is capped at 60000 ms.

### Returns

<ResponseField name="onFilterTokensUpdated" type="FilterTokenUpdates!">
  Current page of matching tokens for the supplied filters. See [FilterTokenUpdates](/api-reference/graphql/types/FilterTokenUpdates).
</ResponseField>

### Arguments

<ResponseField name="filters" type="TokenFilters">
  Filter conditions. See [TokenFilters](/api-reference/graphql/types/TokenFilters).
</ResponseField>

<ResponseField name="rankings" type="[TokenRanking]">
  Sorting criteria. See [TokenRanking](/api-reference/graphql/types/TokenRanking) and [TokenRankingAttribute](/api-reference/graphql/types/TokenRankingAttribute).
</ResponseField>

<ResponseField name="statsType" type="TokenPairStatisticsType">
  `FILTERED` or `UNFILTERED`. See [TokenPairStatisticsType](/api-reference/graphql/types/TokenPairStatisticsType).
</ResponseField>

<ResponseField name="phrase" type="String">
  Search phrase to match against token name or symbol.
</ResponseField>

<ResponseField name="tokens" type="[String]">
  Array of specific token selectors in `"address:networkId"` format.
</ResponseField>

<ResponseField name="excludeTokens" type="[String]">
  Array of token addresses to exclude from results.
</ResponseField>

<ResponseField name="limit" type="Int">
  Maximum number of results to return (default: 25, max: 200).
</ResponseField>

<ResponseField name="offset" type="Int">
  Pagination offset (default: 0).
</ResponseField>

<ResponseField name="updatePeriod" type="Int">
  Update interval in milliseconds (default: `500`, max: `60000`).
</ResponseField>

### Example

```graphql theme={null}
subscription {
  onFilterTokensUpdated(
    filters: {
      network: [1]
      liquidity: { gte: 10000 }
      volume24: { gte: 50000 }
    }
    rankings: [{ attribute: volume24, direction: DESC }]
    updatePeriod: 1000
    limit: 10
  ) {
    updates {
      priceUSD
      liquidity
      marketCap
      volume24
      change24
      buyCount24
      sellCount24
      holders
      token { name symbol address networkId }
    }
  }
}
```

### Subscribe example

Open a `graphql-transport-ws` WebSocket to `wss://api.mobula.io/graphql/subscriptions`, complete the `connection_init` handshake, then send a `subscribe` message:

```json theme={null}
{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription ($filters: TokenFilters, $period: Int, $limit: Int) { onFilterTokensUpdated(filters: $filters, updatePeriod: $period, limit: $limit) { updates { priceUSD liquidity volume24 change24 token { name symbol address networkId } } } }",
    "variables": {
      "filters": { "network": [1], "liquidity": { "gte": 10000 }, "volume24": { "gte": 50000 } },
      "period": 1000,
      "limit": 10
    }
  }
}
```