Get a Select Filter's Choices

GET https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}/filters/{filterId}/options

Lists a select filter's choices: its field's values among the rows the other filters leave and the charts it reaches read, so a value none of them can show is not offered, most rows first, at most 200, each with its rows; an enum's values in the model's order. `search` keeps the values that contain it. The viewer's state is in the query string, as the dashboard's page writes it: each filter by its id (`time=last-6-month`, `status=ACTIVE&status=PENDING`, `amount=100..500`, `!off` to turn a default off, `!null` for (none)), a cross-filter as `x.<block>.<output>=<value>`, and a drill as `d.<block>.<output>=<value>` with `by.<block>=<field>`. A filter the query string leaves out takes its saved default. A value a filter cannot take is refused with INVALID_REQUEST, naming the filter. `_version` names the version of the dashboard the page drew: one saved at another version since is refused with VERSION_CONFLICT before anything is read, its block, filter or state included. Without it, the latest version is read.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID
dashboardId path string yes
filterId path string yes
_version query integer no The version of the dashboard the page reading it drew, as GetAnalyticsDashboard answered it: a dashboard saved at another version since is refused with VERSION_CONFLICT, naming the version it is at, and nothing is read. Without one, the latest version is read.
search query string no Text the values contain, ignoring case.

Responses

200 — The filter's choices

Content-Type: application/json · Schema: AnalyticsDashboardFilterOptions

AnalyticsDashboardFilterOptions fields:

FieldTypeRequiredDescription
values array<object> yes
truncated boolean yes True when there are more values than listed.

401 — No valid token

Content-Type: application/json · Schema: AiErrorResponse

AiErrorResponse fields:

FieldTypeRequiredDescription
error string yes Error message

403 — Not a member of the organization, or DATASET_FORBIDDEN: the query reads a dataset the caller may not read

Content-Type: application/json

404 — NOT_FOUND: no dashboard, or no filter with this id

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

409 — VERSION_CONFLICT: the read names a version the dashboard was saved past; nothing is read

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

422 — INVALID_REQUEST: not a select filter, or a value of the state cannot be read; QUERY_REJECTED, with diagnostics

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

429 — BUSY: too many analytics queries are running

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

500 — ANALYTICS_UNAVAILABLE: an unexpected failure

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready, or the analytics database failed the query; worth a retry

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

504 — TIMEOUT: the query ran past its time limit

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

Example

Generated from this operation's schema. Values are placeholders — substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X GET 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}/filters/{filterId}/options' \
  -H "Authorization: Bearer $SUGER_TOKEN"

Response — 200

{
  "values": [
    {
      "value": "string",
      "rows": 1
    }
  ],
  "truncated": true
}

Error — 401

{
  "error": "string"
}

View as Markdown · API reference overview

Spotted something wrong or out of date on this page? Tell us and we'll correct it.