> ## Documentation Index > Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Canvas Filterable Fields > List the fields a canvas filter can target — custom filters first, then columns by name — with the tiles each reaches and whether viewers are offered it. With includeTableColumns, also every column of the tables behind the charts, to build a custom filter from ## OpenAPI ````yaml get /v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/filterable-fields openapi: 3.1.0 info: title: Upsolve API version: 1.5.0 servers: - url: https://api.upsolve.ai security: [] tags: [] paths: /v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/filterable-fields: get: summary: List the fields a canvas filter can target — cust… description: >- List the fields a canvas filter can target — custom filters first, then columns by name — with the tiles each reaches and whether viewers are offered it. With includeTableColumns, also every column of the tables behind the charts, to build a custom filter from operationId: >- GetV2ApiProjectsProjectIdWorkspacesWorkspaceIdCanvasesCanvasIdFilterableFields parameters: - name: apiKey in: query required: false description: >- Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on. schema: description: >- Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on. type: string minLength: 1 - name: organizationId in: query required: false description: >- The ID of the organization. Required when using Supabase JWT authentication. schema: type: string description: >- The ID of the organization. Required when using Supabase JWT authentication. - name: connectionId in: query required: false description: The ID of the connection a guest has access to schema: type: string description: The ID of the connection a guest has access to - name: projectId in: path required: true description: The project in the URL. The caller's project user is read from it. schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: The project in the URL. The caller's project user is read from it. - name: workspaceId in: path required: true description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/filterable-fields Parameter schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ - name: canvasId in: path required: true description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/filterable-fields Parameter schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ - name: dataModelVersion in: query required: false description: >- Published data model version to resolve fields and run queries against. Defaults to the published version. schema: description: >- Published data model version to resolve fields and run queries against. Defaults to the published version. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - name: includeTableColumns in: query required: false description: >- Also list `tableColumns`: every column of the tables behind the charts, one per table, with the tiles a filter on exactly that table's column reaches. Ask for it to build a custom filter. schema: description: >- Also list `tableColumns`: every column of the tables behind the charts, one per table, with the tiles a filter on exactly that table's column reaches. Ask for it to build a custom filter. format: boolean (preprocessed) responses: '200': description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/filterable-fields Positive response content: application/json: schema: type: object properties: status: type: string const: success data: type: object properties: fields: type: array items: type: object properties: fieldKey: type: string description: >- Identifier of the field. Pass it unchanged as `field` when creating a filter or fetching values; never construct or parse it. kind: default: column description: >- 'custom': one of the canvas's custom filters (its fieldKey is `custom:`), listed before every column. 'column': a column by name. type: string enum: - column - custom customFilter: default: null description: >- The custom filter's definition, on a custom field; else null. type: - object - 'null' properties: id: type: string description: Identifier of the custom filter. name: type: string minLength: 1 maxLength: 120 description: >- The name viewers see on the filter and in their list. columnType: type: string enum: - string - number - date - boolean description: >- The type every one of its columns has, which decides the filter types it takes. fieldKeys: minItems: 1 maxItems: 20 type: array items: type: string description: >- Its columns, in order: `raw:.` keys from GET …/filterable-fields?includeTableColumns=true (or `col:` field keys). On each tile the first column that applies there is the one filtered. itemIds: minItems: 1 type: - array - 'null' items: type: string tileColumns: default: null description: >- Tiles given columns of their own, by tile id: on each, every column listed is filtered, each narrowing its own table, where any other tile filters on the first of `fieldKeys` that applies there. Each column is a `raw:` key of `fieldKeys`. Null when no tile has its own. type: - object - 'null' propertyNames: type: string additionalProperties: minItems: 1 type: array items: type: string required: - id - name - columnType - fieldKeys - itemIds - tileColumns additionalProperties: false hidden: default: false description: >- The builder switched this field off: viewers are not offered it. Always false on a custom field. type: boolean coveredBy: default: [] description: >- Custom filters (by id) with a column of this field's name. A covered field is not offered to viewers, who get the custom filter instead. type: array items: type: string column: type: string description: >- The column's name. One field stands for every column of that name on the canvas — in its charts and in the tables behind them — matched case-insensitively. columnDisplayName: type: - string - 'null' columnType: type: string enum: - string - number - date - boolean description: >- The column's data type, which decides the filter types it accepts. suggestedFilterType: type: string enum: - Input - Select - Number - Date - Toggle description: >- The filter type that fits this column's type best. tables: type: array items: type: object properties: table: type: string description: A data-model table that has the column. column: type: string description: >- The column's name in that table, as the table spells it. tableDisplayName: type: - string - 'null' required: - table - column - tableDisplayName additionalProperties: false description: >- The tables a filter on this field may narrow on a tile whose result does not have the column: the tables behind the charts that show it, or — when no chart shows it — every table behind the charts that has it. Empty for a column only a chart's result has (a computed measure). tableChoices: default: [] description: >- When a chart reads two or more tables that have this column (so a filter on the name alone is ambiguous there): every table behind the charts with the column, each a filter on exactly that table's column. Create a filter on one with `field` set to its fieldKey, or on several with `fieldKeys`. Empty when the name is not ambiguous on any chart. type: array items: type: object properties: fieldKey: type: string description: >- `raw:
.`: pass it unchanged in a custom filter's fieldKeys. table: type: string description: The data-model table. tableDisplayName: type: - string - 'null' column: type: string description: The column's name, as the table spells it. columnDisplayName: type: - string - 'null' columnType: type: string enum: - string - number - date - boolean description: >- The column's data type, which decides the filter types it accepts. reachedItemIds: type: array items: type: string description: >- Tiles a filter on exactly this table's column would narrow. required: - fieldKey - table - tableDisplayName - column - columnDisplayName - columnType - reachedItemIds additionalProperties: false displayedOnItemIds: type: array items: type: string description: >- Chart tiles that show this column, matched by name. These are the fields a viewer most likely wants to filter by; a field no tile shows is a column of the data behind the charts. targets: type: array items: type: object properties: itemId: type: string description: The canvas item (tile) this field reaches. itemName: type: string description: The tile's display name. appliesAs: type: string enum: - raw - output description: >- How a filter on this field is applied to this tile. required: - itemId - itemName - appliesAs additionalProperties: false description: >- Every tile a filter on this field would affect, and how. unreachableItemIds: type: array items: type: string description: >- Chart tiles a filter on this field would NOT affect — tell the user these tiles stay unfiltered. required: - fieldKey - kind - customFilter - hidden - coveredBy - column - columnDisplayName - columnType - suggestedFilterType - tables - tableChoices - displayedOnItemIds - targets - unreachableItemIds additionalProperties: false description: >- Every field a filter can target on this canvas: its custom filters first (kind 'custom'), then one per column name — the columns its charts show and the columns of the tables behind them — with the tiles each reaches and the tiles that show it. On a tile whose chart shows the column a filter keeps the matching rows of the chart; on any other it narrows the one table behind the tile that has the column. Fields the charts show come before the rest. A field marked `hidden` or `coveredBy` a custom filter is not offered to viewers. tableColumns: default: null description: >- With includeTableColumns: every column of the tables behind the charts, for a custom filter's fieldKeys. Null otherwise. type: - array - 'null' items: type: object properties: fieldKey: type: string description: >- `raw:
.`: pass it unchanged in a custom filter's fieldKeys. table: type: string description: The data-model table. tableDisplayName: type: - string - 'null' column: type: string description: The column's name, as the table spells it. columnDisplayName: type: - string - 'null' columnType: type: string enum: - string - number - date - boolean description: >- The column's data type, which decides the filter types it accepts. reachedItemIds: type: array items: type: string description: >- Tiles a filter on exactly this table's column would narrow. required: - fieldKey - table - tableDisplayName - column - columnDisplayName - columnType - reachedItemIds additionalProperties: false dataModelVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- The data model version the fields were resolved against. required: - fields - tableColumns - dataModelVersion additionalProperties: false required: - status - data additionalProperties: false '400': description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/filterable-fields Negative response content: application/json: schema: type: object properties: status: type: string const: error error: type: object properties: message: type: string code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false required: - status - error additionalProperties: false security: - APIKEY_3: [] components: securitySchemes: APIKEY_3: type: apiKey in: header name: authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.