> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Render AI job visualization > Render the visualization from a completed AI job as a PNG image. ## OpenAPI ````yaml /api/openapi.yaml get /v1/ai/jobs/{jobId}/vis openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: Who Am I description: Inspect your own user permissions - name: AI description: AI-powered query generation - name: AI Credit Controls description: Manage organization-level AI credit usage - name: AI Credit Usage description: Monitor AI credit usage - name: AI Evals description: >- Manage prompt sets and runs used to score AI quality against curated prompt suites. - name: AI Model Suggestions description: Manage AI-generated suggestions for shared models - name: AI Routines description: >- Manage Routines, which are scheduled, recurring AI-powered tasks that run automatically on your data - name: Apps description: Draft and publish app documents. - name: App downloads description: Download apps as PNG, PDF, XLSX, or CSV files - name: Documents v2 description: > A draft-based workflow for creating and editing documents: create a document, patch a draft, then publish. - name: Documents description: Create, retrieve, and manage documents - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: IP Allowlist description: Manage the organization's IP allowlist - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Color Palettes description: Manage custom chart color palettes - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Embed description: Manage embed sessions - name: Labels description: | Manage labels in the organization - name: Folders description: Create and organize content folders - name: Folder favorites description: Favorite and unfavorite folders - name: Folder labels description: Apply and manage labels on folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Skills description: >- Manage skills, the saved slash-command instructions the Omni AI assistant runs - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/ai/jobs/{jobId}/vis: get: tags: - AI summary: Render AI job visualization description: | Render the visualization from a completed AI job as a PNG image. operationId: aiJobVisualization parameters: - name: jobId in: path required: true schema: type: string format: uuid description: The unique identifier of the AI job - name: auto_vis in: query schema: type: string default: 'true' description: > The literal string `false` disables automatic chart selection and returns a `204` if the job has no visualization. Any other string, including an empty string and `0`, enables automatic selection. Defaults to `true`. - name: debug in: query schema: type: string default: 'false' description: > Returns debug JSON instead of the rendered PNG when enabled. The strings `false`, `0`, and the empty string disable debug; any other non-empty string, including `true` and `1`, enables it. Defaults to `false`. responses: '200': description: >- Visualization rendered as `image/png`, or `application/json` when debug is enabled or when the underlying data is unavailable. Debug JSON contains the compiled visualization and query details, or diagnostic information when the data is unavailable. content: image/png: schema: type: string format: binary application/json: schema: anyOf: - type: object properties: compiledVegaLiteSpec: type: object additionalProperties: $ref: '#/components/schemas/AiJobVisNonNullJsonValue' description: >- Compiled Vega specification, or `null` if compilation produced no specification. dataSource: type: string enum: - arrow hasQuery: type: boolean enum: - true hasResultFields: type: boolean enum: - true query: $ref: '#/components/schemas/OmniQuery' resultFields: type: array items: type: object properties: label: type: string name: type: string type: type: object properties: typeId: type: integer required: - typeId additionalProperties: $ref: '#/components/schemas/AiJobVisNonNullJsonValue' description: >- Serialized Apache Arrow data type, when available. required: - label - name rowCount: type: integer minimum: 0 visConfig: type: object properties: chartType: type: string enum: - auto - area - areaStacked - areaStackedPercentage - bar - barLine - barGrouped - barStacked - barStackedPercentage - boxplot - code - column - columnGrouped - columnStacked - columnStackedPercentage - heatmap - kpi - line - lineColor - map - regionMap - markdown - omni-ai-summary-markdown - pie - funnel - sankey - point - pointColor - pointSize - pointSizeColor - singleRecord - omni-spreadsheet - summaryValue - svgMap - table - treemap visualization: type: object additionalProperties: $ref: '#/components/schemas/AiJobVisNonNullJsonValue' required: - compiledVegaLiteSpec - dataSource - hasQuery - hasResultFields - query - resultFields - rowCount - visConfig - type: object properties: error: type: string description: >- Human-readable error message describing what went wrong. example: No Arrow IPC data available for visualization hasQuery: type: boolean enum: - false jobId: type: string format: uuid required: - error - hasQuery - jobId '204': description: >- No visualization exists, and `auto_vis=false` disabled automatic chart selection. The response has no body. '400': description: Invalid job ID format. Must be a valid UUID. content: application/json: schema: $ref: '#/components/schemas/ApiError400' '401': description: | Unauthorized Possible error messages: - `Missing or invalid API key` content: application/json: schema: $ref: '#/components/schemas/ApiError401' '403': description: >- Insufficient permissions. AI query generation must be enabled for the organization, and the caller must have permission to use AI on the job's model. content: application/json: schema: $ref: '#/components/schemas/ApiError403' '404': description: >- Job not found, not in `COMPLETE` state, or this endpoint isn't enabled for the organization. content: application/json: schema: $ref: '#/components/schemas/ApiError404' '422': description: > The job completed but can't be rendered as a visualization. Common causes: no visualization action in the job result, no underlying data available, missing summary fields, or the chart type isn't renderable as an image (for example, tables or KPIs). content: application/json: schema: type: object properties: error: type: string description: Human-readable error message describing what went wrong. example: No Arrow IPC data available for visualization required: - error '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: AiJobVisNonNullJsonValue: anyOf: - type: string - type: number - type: boolean - type: array items: oneOf: - $ref: '#/components/schemas/AiJobVisNonNullJsonValue' - type: 'null' - type: object additionalProperties: oneOf: - $ref: '#/components/schemas/AiJobVisNonNullJsonValue' - type: 'null' OmniQuery: type: object properties: aiGenerated: type: boolean description: >- True when AI generated this query’s SQL; the AI SQL is shown in the advanced SQL box. branch_id: type: string description: Branch model ID when querying against a model branch. calculations: type: array items: type: object properties: allow_refs_to_unselected_fields: type: boolean description: >- Set by the Kotlin parser when this calc references fields not selected at the top level (AI SQL-gen produces these; UI-authored calcs do not). anchor_row: type: integer exclusiveMinimum: 0 description: >- The 1-indexed row the Excel-style formula was authored against, so row-relative references resolve to the intended offsets — e.g. a percent-of-previous "=B4/B5" authored on row 5. Only used when sql_expression is omitted; defaults to 1 (B1 = this row). calc_name: type: string description: >- Internal identifier for the calculation, used as the column alias. description: type: string description: Description of the calculation. format: type: string description: Number/date format string (e.g. "#,##0.00"). label: type: string description: Display label shown in the UI. original_formula: type: string description: >- The calculation formula. Prefer referencing selected fields by name (e.g. "=SUM(orders.revenue)") — name references are stable under column reordering and have no row semantics. Excel-style references also work: column letters map to the query's fields in table order (A = the first field) with rows anchored at row 1 (set anchor_row to author row-relative references against a different row), and calc columns can only be referenced by letter. When sql_expression is omitted, the server parses this formula on write and rejects the request if it does not parse. outside_pivot: type: boolean description: >- When true, the calculation is evaluated outside the pivot grouping. pushdown: type: boolean nullable: true description: >- Per-calc override for whether to evaluate before the row limit. `null` defers to the model-level default. sql: type: string description: Compiled SQL string produced from the formula. sql_expression: description: >- Parsed SQL expression tree (serialized, server-internal format). Omit it to have the server parse original_formula instead. swallow_errors: type: boolean description: >- When true, calculation errors are silently swallowed instead of surfaced. required: - calc_name additionalProperties: {} description: Table calculations attached to this query. column_limit: type: number description: Max number of pivot columns to return. column_totals: type: object additionalProperties: type: object properties: type: type: string enum: - aggregation required: - type description: Column-level aggregation totals, keyed by field name. controls: type: array items: oneOf: - type: object properties: description: type: string hidden: type: boolean id: type: string label: type: string display: type: string enum: - SELECT - BUTTON_TOGGLE field: type: string kind: type: string enum: - FIELD - TIMEFRAME options: type: array items: type: object properties: isDimension: type: boolean label: type: string topicLabel: type: string value: type: string viewLabel: type: string required: - label - value type: type: string enum: - FIELD_SELECTION required: - id - field - kind - options - type - type: object properties: description: type: string hidden: type: boolean id: type: string label: type: string display: type: string enum: - SELECT - BUTTON_TOGGLE options: type: array items: type: object properties: label: type: string value: type: string required: - label - value selectionMap: type: object additionalProperties: type: object additionalProperties: type: string type: type: string enum: - MULTI_FIELD_SELECTION value: type: string required: - id - options - selectionMap - type - type: object properties: computations: type: array items: type: object properties: filterId: type: string isDynamicPreviousPeriod: type: boolean periodsAgo: type: number nullable: true timeUnitName: type: string nullable: true required: - periodsAgo - timeUnitName filterFieldName: type: string filterId: type: string id: type: string type: type: string enum: - PERIOD_OVER_PERIOD required: - computations - filterFieldName - id - type - type: object properties: description: type: string hidden: type: boolean id: type: string label: type: string fieldOrder: type: string enum: - query - control options: type: array items: type: object properties: isDimension: type: boolean label: type: string topicLabel: type: string value: type: string viewLabel: type: string required: - label - value type: type: string enum: - FIELD_PICKER values: type: array items: type: string required: - id - options - type - type: object properties: description: type: string hidden: type: boolean id: type: string label: type: string conjunction: type: string enum: - OR filters: type: array items: type: object properties: fieldName: type: string filter: $ref: '#/components/schemas/JsonValue' id: type: string required: - fieldName - filter - id type: type: string enum: - MULTI_FIELD_FILTER required: - id - conjunction - filters - type - type: object properties: description: type: string hidden: type: boolean id: type: string label: type: string fieldSelection: oneOf: - type: object properties: mode: type: string enum: - full-model required: - mode - type: object properties: mode: type: string enum: - auto topics: type: array items: type: string required: - mode - topics - type: object properties: fields: type: array items: type: object properties: fieldName: type: string topicName: type: string required: - fieldName mode: type: string enum: - specific required: - fields - mode includeViewNameInLabels: type: boolean type: type: string enum: - DYNAMIC_FILTER required: - id - fieldSelection - type - type: object properties: description: type: string hidden: type: boolean id: type: string label: type: string defaultValue: type: integer minimum: 1 field: type: string max: type: integer minimum: 1 min: type: integer minimum: 1 type: type: string enum: - TOP_N value: type: integer minimum: 1 required: - id - defaultValue - field - type - value description: >- Interactive controls (field selectors, PoP controls) attached to this query. cube_metadata: type: object properties: cube_name: type: string hash_key: type: string topic_name: type: string required: - cube_name - hash_key - topic_name additionalProperties: {} description: >- Cube-specific metadata (topic name, cube name, hash key) for cube-backed queries. custom_summary_types: type: object additionalProperties: type: string description: Per-field custom summary functions (e.g. SUM, AVG, COUNT). dbtFileName: type: string description: dbt file name when this query is backed by a dbt model. dbtMode: type: boolean description: Whether this query is in dbt mode. default_group_by: type: boolean description: >- When true, all dimensions are implicitly included in GROUP BY, unless the model's default_group_by setting (never or primary_key) suppresses it. dimensionIndex: type: number description: Index of the primary dimension used for result ordering. executableSQL: type: string description: Server-compiled SQL string (read-only, set by the backend). fields: type: array items: type: string description: Model field names selected for the query (dimensions + measures). fill_fields: type: array items: type: string description: >- Fields whose missing date/time values should be filled with nulls to create continuous series. filters: type: object additionalProperties: oneOf: - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean appliedLabels: type: object additionalProperties: type: string case_insensitive: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - CONTAINS - ENDS_WITH - STARTS_WITH - EQUALS - IS_EMPTY - SQL_LIKE type: type: string enum: - string values: type: array items: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - kind - type - values additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_inclusive: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - LESS_THAN - GREATER_THAN - EQUALS - BETWEEN type: type: string enum: - number values: type: array items: anyOf: - type: string - type: number appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - kind - type - values additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean isFiscal: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - IS_ON_DAY_OF_WEEK - IS_ON_DAY_OF_QUARTER - IS_IN_MONTH_OF_YEAR - IS_ON_DAY_OF_YEAR - IS_AT_HOUR_OF_DAY - IS_IN_QUARTER_OF_YEAR - IS_IN_WEEK_OF_YEAR - IS_ON_DAY_OF_MONTH - BETWEEN - ON_OR_AFTER - BEFORE - TIME_FOR_INTERVAL_DURATION - TIME_FOR_UNIT_DURATION - QUERY_OFFSET left_side: type: string nullable: true offset_interval_string: type: string nullable: true right_side: type: string nullable: true type: type: string enum: - date ui_type: type: string nullable: true enum: - ANY_TIME - BEFORE - BETWEEN - MONTH_OF_YEAR - PAST - YEAR - DAY - IS_ON_DAY_OF_WEEK - ON_OR_AFTER - IS_IN_THE_MONTH - IS_IN_THE_QUARTER - IS_IN_THE_FISCAL_QUARTER - IS_IN_THE_FISCAL_YEAR - TIME_FOR_INTERVAL_DURATION - TIME_FOR_UNIT_DURATION - CUSTOM - null appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - kind - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_negative: type: boolean nullable: true type: type: string enum: - 'null' appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_negative: type: boolean nullable: true treat_nulls_as_false: type: boolean type: type: string enum: - boolean appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean disregard_limit: type: boolean field_name: type: string is_negative: type: boolean nullable: true query_id: type: string type: type: string enum: - query view_query: type: object properties: fields: type: array items: type: string filters: type: object additionalProperties: {} default: {} limit: type: number sorts: type: array items: {} default: [] table: type: string required: - fields additionalProperties: {} appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean type: type: string enum: - user_attribute user_attribute_name: type: string appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type - user_attribute_name additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean conjunction: type: string enum: - OR - AND filters: type: array items: $ref: '#/components/schemas/CompositeFilter' is_negative: type: boolean nullable: true type: type: string enum: - composite appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - conjunction - filters - type additionalProperties: {} description: Query filters keyed by filter ID. filtersUsedInSql: type: object additionalProperties: oneOf: - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean appliedLabels: type: object additionalProperties: type: string case_insensitive: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - CONTAINS - ENDS_WITH - STARTS_WITH - EQUALS - IS_EMPTY - SQL_LIKE type: type: string enum: - string values: type: array items: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - kind - type - values additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_inclusive: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - LESS_THAN - GREATER_THAN - EQUALS - BETWEEN type: type: string enum: - number values: type: array items: anyOf: - type: string - type: number appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - kind - type - values additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean isFiscal: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - IS_ON_DAY_OF_WEEK - IS_ON_DAY_OF_QUARTER - IS_IN_MONTH_OF_YEAR - IS_ON_DAY_OF_YEAR - IS_AT_HOUR_OF_DAY - IS_IN_QUARTER_OF_YEAR - IS_IN_WEEK_OF_YEAR - IS_ON_DAY_OF_MONTH - BETWEEN - ON_OR_AFTER - BEFORE - TIME_FOR_INTERVAL_DURATION - TIME_FOR_UNIT_DURATION - QUERY_OFFSET left_side: type: string nullable: true offset_interval_string: type: string nullable: true right_side: type: string nullable: true type: type: string enum: - date ui_type: type: string nullable: true enum: - ANY_TIME - BEFORE - BETWEEN - MONTH_OF_YEAR - PAST - YEAR - DAY - IS_ON_DAY_OF_WEEK - ON_OR_AFTER - IS_IN_THE_MONTH - IS_IN_THE_QUARTER - IS_IN_THE_FISCAL_QUARTER - IS_IN_THE_FISCAL_YEAR - TIME_FOR_INTERVAL_DURATION - TIME_FOR_UNIT_DURATION - CUSTOM - null appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - kind - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_negative: type: boolean nullable: true type: type: string enum: - 'null' appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_negative: type: boolean nullable: true treat_nulls_as_false: type: boolean type: type: string enum: - boolean appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean disregard_limit: type: boolean field_name: type: string is_negative: type: boolean nullable: true query_id: type: string type: type: string enum: - query view_query: type: object properties: fields: type: array items: type: string filters: type: object additionalProperties: {} default: {} limit: type: number sorts: type: array items: {} default: [] table: type: string required: - fields additionalProperties: {} appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean type: type: string enum: - user_attribute user_attribute_name: type: string appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - type - user_attribute_name additionalProperties: {} - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean conjunction: type: string enum: - OR - AND filters: type: array items: $ref: '#/components/schemas/CompositeFilter' is_negative: type: boolean nullable: true type: type: string enum: - composite appliedLabels: type: object additionalProperties: type: string base_view: type: string description: type: string fieldName: type: string filterControlType: anyOf: - type: string enum: - multiValueEquals - singleValueEquals - type: string enum: - singleDay - timeframe hidden: type: boolean label: type: string required: type: boolean requiredScope: type: string enum: - dashboard - tiles topic: type: string watchedContainerIds: type: array items: type: string required: - conjunction - filters - type additionalProperties: {} description: Filters that were embedded directly in raw SQL (read-only). imported_model_ids: type: array items: type: string description: >- Model IDs (UUIDs) the query reaches through its composite topic's imports — the topic's import_models entries, which must be model ids, not names. Authorization requires the run gate on each; omit only for queries that do not touch imported topics. join_paths_from_topic_name: type: string description: >- Name of the topic the query runs on; it also sets join path precedence. join_via_map: type: object additionalProperties: type: array items: type: string description: >- Virtual topic join path overrides, keyed by view name to ordered join path. limit: type: number description: Row limit for the query. manualSort: type: boolean description: When true, the user has explicitly set a custom sort order. metadata: type: object additionalProperties: type: object properties: format: type: string label: type: string order: type: number additionalProperties: {} description: Per-field display metadata (format, label, order). modelId: type: string description: The model ID this query runs against. model_extension_id: type: string description: ID of a model extension layered on top of the base model. offset: type: number description: Row offset for pagination. parsed: type: boolean description: Whether this raw SQL query has been parsed into a semantic query. periodOverPeriodTransposed: type: boolean description: Whether the period-over-period comparison columns are transposed. period_over_period_computations: type: array items: type: object properties: date_filter_field_name: type: string description: The date dimension field this comparison is anchored to. date_filter_id: type: string description: >- ID of the date filter being offset (if backed by a dashboard filter). is_dynamic_previous_period: type: boolean description: >- When true, the previous period is calculated dynamically relative to the current filter range. periods_ago: type: number nullable: true description: >- How many periods back to compare (e.g. 1 = previous period). Null if not set. time_unit_name: type: string nullable: true description: >- Time grain for the offset (e.g. "month", "year"). Null if not set. required: - date_filter_field_name - periods_ago - time_unit_name additionalProperties: {} description: Period-over-period comparison configurations. pivots: type: array items: type: string description: Field names to pivot on (columns become values). rewriteSql: type: boolean description: When true, the backend should rewrite/optimize the SQL. row_totals: type: object additionalProperties: type: object properties: type: type: string enum: - aggregation required: - type description: Row-level aggregation totals, keyed by field name. sorts: type: array items: type: object properties: column_name: type: string description: The model field name to sort by. is_column_sort: type: boolean description: >- When true, this sort targets a pivoted column rather than a row dimension. pivot_value_map: type: object additionalProperties: type: string nullable: true description: >- Maps pivot field names to specific pivot values, scoping the sort to a single pivot column. sort_descending: type: boolean description: When true, sort order is descending. subtotal_sort: type: string description: Field name whose subtotal row should be used as the sort key. required: - column_name - sort_descending additionalProperties: {} description: Sort clauses applied to the query result set. sqlSortsEnabled: type: boolean description: Whether user-created sorts are enabled on a raw SQL query. staticQueryReferences: type: object additionalProperties: {} description: >- Pre-computed query references for AI chat context. Inner shape is `OmniQuery & { model_id: string }`; left as `unknown` to avoid a recursive zod schema. Validated structurally by consumers when they execute the referenced sub-queries. table: type: string description: Base view (table) name in the model. transposed_measures: type: array items: type: string description: Measure field names that have been transposed into rows. userEditedSQL: type: string description: User-authored raw SQL (empty string when not in SQL mode). version: type: number description: Schema version for migration support. required: - calculations - column_totals - fields - fill_fields - filters - modelId - pivots - row_totals - sorts - table - userEditedSQL additionalProperties: {} ApiError400: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 400 required: - detail - status ApiError401: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. example: 'Unauthorized: Missing or invalid API key' status: type: integer description: HTTP status code of the error. example: 401 required: - detail - status ApiError403: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 403 required: - detail - status ApiError404: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 404 required: - detail - status JsonValue: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: oneOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' - type: array items: oneOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' description: Arbitrary JSON value (string, number, boolean, null, object, or array). CompositeFilter: type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean conjunction: type: string enum: - OR - AND filters: type: array items: anyOf: - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean appliedLabels: type: object additionalProperties: type: string case_insensitive: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - CONTAINS - ENDS_WITH - STARTS_WITH - EQUALS - IS_EMPTY - SQL_LIKE type: type: string enum: - string values: type: array items: type: string required: - kind - type - values - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_inclusive: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - LESS_THAN - GREATER_THAN - EQUALS - BETWEEN type: type: string enum: - number values: type: array items: anyOf: - type: string - type: number required: - kind - type - values - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean isFiscal: type: boolean is_negative: type: boolean nullable: true kind: type: string enum: - IS_ON_DAY_OF_WEEK - IS_ON_DAY_OF_QUARTER - IS_IN_MONTH_OF_YEAR - IS_ON_DAY_OF_YEAR - IS_AT_HOUR_OF_DAY - IS_IN_QUARTER_OF_YEAR - IS_IN_WEEK_OF_YEAR - IS_ON_DAY_OF_MONTH - BETWEEN - ON_OR_AFTER - BEFORE - TIME_FOR_INTERVAL_DURATION - TIME_FOR_UNIT_DURATION - QUERY_OFFSET left_side: type: string nullable: true offset_interval_string: type: string nullable: true right_side: type: string nullable: true type: type: string enum: - date ui_type: type: string nullable: true enum: - ANY_TIME - BEFORE - BETWEEN - MONTH_OF_YEAR - PAST - YEAR - DAY - IS_ON_DAY_OF_WEEK - ON_OR_AFTER - IS_IN_THE_MONTH - IS_IN_THE_QUARTER - IS_IN_THE_FISCAL_QUARTER - IS_IN_THE_FISCAL_YEAR - TIME_FOR_INTERVAL_DURATION - TIME_FOR_UNIT_DURATION - CUSTOM - null required: - kind - type - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_negative: type: boolean nullable: true type: type: string enum: - 'null' required: - type - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean is_negative: type: boolean nullable: true treat_nulls_as_false: type: boolean type: type: string enum: - boolean required: - type - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean disregard_limit: type: boolean field_name: type: string is_negative: type: boolean nullable: true query_id: type: string type: type: string enum: - query view_query: type: object properties: fields: type: array items: type: string filters: type: object additionalProperties: {} default: {} limit: type: number sorts: type: array items: {} default: [] table: type: string required: - fields additionalProperties: {} required: - type - type: object properties: cancel_query_filter: type: boolean exclude_from_bind_all: type: boolean ignore_if_unjoinable: type: boolean type: type: string enum: - user_attribute user_attribute_name: type: string required: - type - user_attribute_name - $ref: '#/components/schemas/CompositeFilter' description: >- Child filters — each a simple filter or another composite filter. Recursive; see the dashboard-filters reference for the full grammar. is_negative: type: boolean nullable: true type: type: string enum: - composite required: - conjunction - filters - type Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#token-types). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.