> ## 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. # Run Canvas Item > Run one canvas tile with the canvas filters that reach it, and report which filters applied ## OpenAPI ````yaml post /v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run 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}/items/{itemId}/run: post: summary: Run one canvas tile with the canvas filters that … description: >- Run one canvas tile with the canvas filters that reach it, and report which filters applied operationId: >- PostV2ApiProjectsProjectIdWorkspacesWorkspaceIdCanvasesCanvasIdItemsItemIdRun parameters: - 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: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run 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: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run 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: itemId in: path required: true description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run 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})$ requestBody: description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run Request body content: application/json: schema: type: object properties: apiKey: 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 organizationId: type: string description: >- The ID of the organization. Required when using Supabase JWT authentication. connectionId: type: string description: The ID of the connection a guest has access to tz: description: >- The viewer's UTC offset in hours. Used only when the canvas follows each viewer's own time zone; otherwise the canvas's time zone decides how dates are grouped and filtered. type: number forProjectUserId: description: >- Project user to run the query as; their properties drive the data model's row-level security. Required with an admin credential, ignored for a project-user token. type: string dataModelVersion: description: >- Published data model version to resolve fields and run queries against. Defaults to the published version. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 canvasVersion: description: >- A saved canvas version to run the tile from, with that version's filters. Defaults to the live canvas. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 filterValues: description: Session values for this canvas's filters, by filter id. type: array items: type: object properties: filterId: type: string description: A filter on this canvas. selectedValue: description: >- The value to use for this run instead of the stored one. required: - filterId - selectedValue adhocFilters: description: >- Filters to apply for this run only (not saved), expressed against catalog fields. type: array items: type: object properties: field: type: string description: >- The `fieldKey` of a field from GET …/filterable-fields — a column's, or a custom filter's (`custom:`). The server resolves it into per-tile targets. filterType: type: string enum: - Input - Select - Number - Date - Toggle description: >- Filter type. Must suit the field's columnType: Select (string/date), Number (number), Date (date), Input (any). Toggle is not supported on canvases. filterSubType: anyOf: - type: string enum: - Input Equals - Input Starts with - Input Ends with - Input Contains - type: string enum: - Select Single - Select Multi - type: string enum: - Number Greater than - Number Greater than or equal to - Number Less than - Number Less than or equal to - Number Equal to - type: string enum: - Date Single - Date Range - Date Range (No Timestamp) - Date After - Date Before - type: 'null' description: >- Operator, from the filterType's own list (e.g. 'Select Multi', 'Number Greater than', 'Date Range'). Null for Toggle. displayName: description: >- Label shown on the filter pill. Defaults to the field's columnDisplayName, else the column name. type: string minLength: 1 fieldKeys: description: >- Tables picked under one column name, each a `raw:.` key from a field's tableChoices, all of one type: each chart is filtered on every one of these tables it reads, or not at all, and a chart that reads none of them is not filtered (even one showing a column of the name). `field` must be the first of them. minItems: 1 type: array items: type: string itemIds: description: >- Restrict the filter to these tiles. Each must be one of the field's targets. Defaults to every target. minItems: 1 type: array items: type: string selectedValue: description: >- Initial value. Omit to create the filter with no value (inactive). anyOf: - anyOf: - type: string - type: number - {} - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - {} - type: boolean - type: 'null' description: >- An array is used when multiple values are selected, as with the date range filter, or with a multi-select filter. required: - field - filterType - filterSubType description: A filter expressed against a catalog field. required: [] responses: '200': description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run Positive response content: application/json: schema: type: object properties: status: type: string const: success data: type: object properties: message: type: string queryResult: type: array items: type: object propertyNames: type: string additionalProperties: {} error: type: string unauthorizedTables: type: array items: type: string profiling: type: object properties: profile_breakdown: type: object propertyNames: type: string additionalProperties: type: number compiled_sql: type: string original_sql: type: string required: - profile_breakdown - compiled_sql - original_sql additionalProperties: false filterCoverage: type: object properties: applied: type: array items: type: object properties: filterId: type: - string - 'null' displayName: type: string fieldKey: type: - string - 'null' appliesAs: type: string enum: - raw - output description: >- 'output': the tile's result has the column (its chart shows it), so the tile's rows are filtered — the chart keeps its numbers for the rows it keeps. 'raw': the tile's result does not have the column, so the one table behind the tile that has it is pre-filtered and the chart is computed from its matching rows. required: - filterId - displayName - fieldKey - appliesAs additionalProperties: false description: Active filters that narrowed this tile. skipped: type: array items: type: object properties: filterId: type: - string - 'null' displayName: type: string fieldKey: type: - string - 'null' reason: type: string description: Why this filter did not apply to this tile. required: - filterId - displayName - fieldKey - reason additionalProperties: false description: >- Active filters that did NOT narrow this tile, and why. required: - applied - skipped additionalProperties: false description: >- Which active canvas filters this tile's result reflects. truncated: description: >- A tool tile (rows read from an API) only: true when more rows matched than the tile keeps, so the rows returned are the first 5,000. type: boolean needsConnection: description: >- A tool tile only: set when the tile reads an API the viewer must connect first (their own login or key). There are no rows then; `error` says so. type: object properties: connectorId: 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 API connector the tile reads, which the viewer must connect. connectorName: type: string description: The API's name, as the Connections panel shows it. action: type: - string - 'null' enum: - connect_oauth - add_key - reconnect required: - connectorId - connectorName - action additionalProperties: false required: - message - queryResult - filterCoverage additionalProperties: false required: - status - data additionalProperties: false '400': description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run 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.