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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
429 — BUSY: too many analytics queries are running
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
500 — ANALYTICS_UNAVAILABLE: an unexpected failure
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
504 — TIMEOUT: the query ran past its time limit
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
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.