Endpoints that support returning lots of data, usually but not always GETing a List of Resources, may support filtering.

If the endpoint supports filtering, it will return a ”filtering” root key in the response:

"filtering": {
  "available": <list of filterable fields, their filterable values, and the types of these values >,
  "current": <list of objects describing current filtering>

This should be present in every response from filterable APIs, even if the user has not asked for filtering. For example, if I list all insights via GET https://api.cloudzero.com/v2/insights, I should see a response like:

"insights": [...],
"filtering": {
  "available": [
      "field": "status",
      "valid_values": [
      "valid_types": [
  "current": {
    "status": ["in_progress", "new"]

A client controls the filtering of items via mapping the field key to a single valid_values parameter. These field key/value pairs are repeatable:

GET https://api.cloudzero.com/v2/insights?status=in_progress&status=new