# 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](https://doc.fours.com/settings/oauth-app/)._

### Request

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

### Response — 200

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

### Error — 401

```json
{
  "error": "string"
}
```

---

API reference: https://doc.fours.com/api/
