Look up report filter values

POST/v2/reports/filter-values

Returns the available values for a filterable attribute — use it to build valid filters rules for POST /v2/reports/query.

Works for attributes whose values live in your workspace data (tags, teammates, teams, companies, plans, countries, …). Attributes with staticOptions in the catalog don’t need this endpoint — their value set is already inline.

query narrows results by search string
selectedValues resolves labels for values you already hold (returned alongside search results)

Example

{ "fieldId": "conversation.tags", "query": "bill", "limit": 20 }

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer, and only for workspaces with the Reports product enabled (404 otherwise).

Header ParametersExpand Collapse

"Featurebase-Version": optional "2026-08-19.orbit" or "2026-01-01.nova" or "2025-12-12.clover"

One of the following:

"2026-08-19.orbit"

"2026-01-01.nova"

"2025-12-12.clover"

Body ParametersJSONExpand Collapse

fieldId: string

Attribute ID to look up values for (must have valueSource: "remote_search" or static options in the catalog).

minLength1

maxLength512

cursor: optional string

minLength1

maxLength255

datasetId: optional string

minLength1

maxLength512

groupBy: optional string

minLength1

maxLength512

limit: optional number

Maximum number of options to return (1-50, default 20).

minimum1

maximum50

lookupContextKey: optional string

Opaque client context echoed by the response so stale lookup results can be discarded safely.

minLength1

maxLength1024

metricId: optional string

minLength1

maxLength512

query: optional string

Optional search string to narrow the returned options.

maxLength255

segmentBy: optional string

minLength1

maxLength512

selectedValues: optional array of string

Already-selected values to resolve labels for (returned alongside search results).

ReturnsExpand Collapse

data: array of ReportAttributeOption { label, value, presentation }

label: string

value: string

presentation: optional object { kind, color, icon, 3 more }

kind: "brand" or "company" or "country" or 11 more

One of the following:

"brand"

"company"

"country"

"knowledge_source"

"plain"

"sla"

"tag"

"team"

"teammate"

"ticket_category"

"ticket_state"

"ticket_type"

"user"

"workflow"

color: optional string

icon: optional unknown

iconSvg: optional string

imageUrl: optional string

secondaryLabel: optional string

object: "list"

lookupContextKey: optional string

nextCursor: optional string

truncated: optional boolean

unavailableSelectedValues: optional array of string

Look up report filter values

curl https://do.featurebase.app/v2/reports/filter-values \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY" \
    -d '{
          "fieldId": "conversation.tags",
          "query": "bill"
        }'

{
  "data": [
    {
      "label": "label",
      "value": "value",
      "presentation": {
        "kind": "brand",
        "color": "color",
        "icon": {},
        "iconSvg": "iconSvg",
        "imageUrl": "imageUrl",
        "secondaryLabel": "secondaryLabel"
      }
    }
  ],
  "object": "list",
  "lookupContextKey": "lookupContextKey",
  "nextCursor": "nextCursor",
  "truncated": true,
  "unavailableSelectedValues": [
    "string"
  ]
}

Returns Examples

{
  "data": [
    {
      "label": "label",
      "value": "value",
      "presentation": {
        "kind": "brand",
        "color": "color",
        "icon": {},
        "iconSvg": "iconSvg",
        "imageUrl": "imageUrl",
        "secondaryLabel": "secondaryLabel"
      }
    }
  ],
  "object": "list",
  "lookupContextKey": "lookupContextKey",
  "nextCursor": "nextCursor",
  "truncated": true,
  "unavailableSelectedValues": [
    "string"
  ]
}