Reports

Look up report filter values

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

POST

/v2/reports/filter-values

curl --request POST \
  --url https://do.featurebase.app/v2/reports/filter-values \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cursor": "<string>",
  "datasetId": "<string>",
  "fieldId": "conversation.tags",
  "groupBy": "<string>",
  "limit": 123,
  "lookupContextKey": "<string>",
  "metricId": "<string>",
  "query": "bill",
  "segmentBy": "<string>",
  "selectedValues": [
    "<string>"
  ]
}
'

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

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).

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

cursorstring

Required string length: 1 - 255

datasetIdstring

Required string length: 1 - 512

fieldIdstringrequired

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

Required string length: 1 - 512

Example: conversation.tags

groupBystring

Required string length: 1 - 512

limitinteger

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

Required range: 1 <= x <= 50

lookupContextKeystring

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

Required string length: 1 - 1024

metricIdstring

Required string length: 1 - 512

querystring

Optional search string to narrow the returned options.

Maximum string length: 255

Example: bill

segmentBystring

Required string length: 1 - 512

selectedValuesstring[]

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

Maximum array length: 50

Response

Success

dataobject[]required

Show child attributes

lookupContextKeystring

nextCursorstring

objectenum<string>required

Available options: list

truncatedboolean

unavailableSelectedValuesstring[]

Still need help? Ask the team