Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Visier Data Out Data Query API
description: Visier APIs for getting data out of Visier, such as aggregate data and data version information.
license:
name: Apache License, Version 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 22222222.99201.3040
security:
- ApiKeyAuth: []
BearerAuth: []
- ApiKeyAuth: []
CookieAuth: []
- ApiKeyAuth: []
OAuth2Auth: []
tags:
- name: DataQuery
x-displayName: Data Query
description: Query against your data in Visier to get aggregate and list data.
paths:
/v1/data/query/aggregate:
post:
tags:
- DataQuery
summary: Query aggregate data
description: "To retrieve aggregated values from your data in Visier, you can perform an aggregation. Usually, an aggregation\n retrieves values over a period of time, such as multiple months. You can also group and filter your data in an\n aggregation query to retrieve detailed information."
operationId: DataQuery_Aggregate
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the current project's data version or the production version if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.AggregationQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: Aggregate query response
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.CellSetOrErrorDTO'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
/v1/data/query/connector-version:
get:
tags:
- DataQuery
summary: Retrieve a data out connector's latest version
description: Retrieve the latest released version of a data out connector. Use this endpoint to automate checking connector release versions.
operationId: DataQuery_ConnectorVersion
parameters:
- name: connectorId
in: query
description: "The name of the connector for which to retrieve the latest version. Valid values:\n - `powerbi`: Retrieve the latest version of Visier's Power BI connector.\n - `tableau`: Retrieve the latest version of Visier's Tableau connector."
schema:
enum:
- powerbi
- tableau
type: string
format: enum
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.ConnectorVersionDTO'
security:
- {}
/v1/data/query/list:
post:
tags:
- DataQuery
summary: Query a list of details
description: "To retrieve a list of values for specific objects, you can perform a list query. A list query provides information\n about values for selected data points, and is not an aggregated value. In Visier's interface, a list query is\n comparable to View Details for a specific data point in a visualization."
operationId: DataQuery_List
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the data version released by the current project or production version, if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.ListQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: List query response
content:
application/json:
schema:
$ref: '#/components/schemas/data_out.ListResponse'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
/v1/data/query/snapshot:
post:
tags:
- DataQuery
summary: Query a series of detailed snapshots
description: "To retrieve a collection of `list` query-style snapshots taken at the defined intervals, execute a `snapshot` query.\n Each snapshot in the result is associated with a timestamp, or the \"effective date\" at which date snapshot data was valid.\n This API allows you to request a detailed time series from Visier.\n\n Structurally, a `snapshot` query is similar to a `list` query, but has the following differences:\n * The `snapshot` query may contain a column, `effectiveDateProperty`, that specifies the time for each snapshot. To include the `effectiveDateProperty` column, add the following object to the columns array:\n ```json\n {\n \"columnName\": \"Snapshot_Date\",\n \"columnDefinition\": {\n \"effectiveDateProperty\": {}\n }\n }\n ```\n * The `snapshot` query uses `timeIntervals` (like an `aggregate` query) instead of `timeInterval` (like a `list` query) because the `snapshot` query\n must specify the number of snapshots to generate. To specify the number of snapshots to generate, use the `intervalCount` property in the `timeIntervals` object, as shown next.\n ```json\n {\n \"timeIntervals\": {\n \"fromDateTime\": \"2022-01-01\",\n \"intervalPeriodType\": \"MONTH\",\n \"intervalPeriodCount\": 6,\n \"intervalCount\": 4\n }\n ```"
operationId: Query_Snapshot
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the data version released by the current project or production version, if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.SnapshotQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: List query response
content:
application/json:
schema:
$ref: '#/components/schemas/data_out.ListResponse'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
/v1/data/query/sql:
post:
tags:
- DataQuery
summary: Query aggregate or list data using SQL-like syntax
description: "To retrieve a list of values for specific objects or aggregate values from metrics, you can write queries using SQL-like syntax.\n The response format matches the query type whether aggregate or list. If requested, aggregate query results may be flattened into tabular format.\n\n A SQL-like query is an aggregate if it contains at least one metric. Aggregate queries must specify a time interval divided into periods; for example:\n ```sql\n SELECT\n employeeCount() AS \"Employee Count\",\n level(Gender, \"Gender\") AS Gender\n FROM\n Employee\n WHERE\n Visier_Time IN periods(date(\"2023-01-01\"), 4, period(3, Month));\n ```\n\n A SQL-like query is a list if it does not contain any metrics. List queries define time intervals as simple intervals; for example:\n ```sql\n SELECT\n EmployeeID AS \"Employee ID\",\n level(Gender, \"Gender\") AS Gender\n FROM\n Employee\n WHERE\n Visier_Time BETWEEN date(\"2022-01-01\") AND date(\"2023-01-01\");\n ```"
operationId: DataQuery_SqlLike
parameters:
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
- name: ProjectID
in: header
description: Optionally, specify a project in which to make the request. If omitted, the request uses the production version.
schema:
type: string
format: uuid
- name: DataVersionID
in: header
description: Optionally, specify a data version against which to execute the query. If omitted, the request uses the data version released by the current project or production version, if no project is specified.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/dataservices.query.SqlLikeQueryExecutionDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: List query response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TableResponseDTO'
- $ref: '#/components/schemas/dataservices.query.CellSetDTO'
application/jsonlines:
schema:
type: string
text/csv:
schema:
type: string
components:
schemas:
dataservices.query.QueryDimensionLevelSelectionDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A dimension and its qualifying path to query.
levelIds:
type: array
items:
type: string
description: A list of level IDs for the dimension levels that you want to query. For example, ["Level_1", "Level_2"]. To get a dimension's level IDs, call the Data Model API.
levelDepths:
type: array
items:
type: integer
format: int32
description: A list of level depths for the dimension levels that you want to query. For a parent-child dimension, depth must be greater than 0. For example, [1, 2]. To get a dimension's level depths, call the Data Model API.
description: "A QueryDimensionLevelSelection allows you to select a dimension level and its members without\n explicitly listing each member."
dataservices.query.AggregationQuerySourceMetricsDTO:
type: object
properties:
columns:
type: array
items:
$ref: '#/components/schemas/dataservices.query.AggregationQuerySourceMetricDTO'
description: An array of metric columns.
description: "The IDs and column names of multiple metrics.\n\n **Note:**\n Only available when the `Accept` header is `text/csv`."
dataservices.datamodel.DimensionReferenceDTO:
type: object
properties:
name:
type: string
description: The ID of the dimension. To get a dimension's ID, call the Data Model API.
qualifyingPath:
type: string
description: "The qualifying path to the dimension in Visier, such as the analytic object or event the dimension is\n associated with. If the path has multiple objects, each object is separated by a period."
description: The name and qualifying path of a dimension to query.
dataservices.query.AggregationQueryDTO:
type: object
properties:
source:
allOf:
- $ref: '#/components/schemas/dataservices.query.AggregationQuerySourceDTO'
description: The source data, such as a metric or formula, to query.
filters:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryFilterDTO'
description: "The objects by which to filter the query, such as dimensions or concepts.\n A filter defines the population to retrieve data from. Omit `filters` if no filtering is required."
axes:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryAxisDTO'
description: "The objects by which to group the query. An axis defines the groups that the data belongs to.\n Omit `axes` if no grouping is required."
timeIntervals:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryTimeIntervalsDTO'
description: The time intervals to query.
parameterValues:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryParameterValueDTO'
description: The values associated with parameters, if defined.
description: "An AggregationQuery defines the data to query in an aggregation query and returns a `cell set` calculated from\n the selected data points."
dataservices.query.QueryMemberMapSelectionDTO:
type: object
properties:
memberMap:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A member map and its qualifying path to query.
targetDimensionName:
type: string
description: The name of the member map's dimension that you want to query. The member selection is based on this dimension.
members:
type: array
items:
$ref: '#/components/schemas/dataservices.common.DimensionMemberReferenceDTO'
description: A collection of the selected dimension members from the `targetDimension`. This must contain at least one member.
description: "A QueryMemberMapSelection groups data in a query by dimension members in a member map.\n This allows grouping by a dimension that isn't typically valid on the analytic object being\n queried by selecting a valid member map on the analytic object.\n Note: This is unique to the data query API and cannot be reproduced in Visier's interface."
dataservices.query.QueryFilterDTO:
type: object
properties:
formula:
type: string
description: A filter expressed as a formula.
selectionConcept:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.SelectionConceptReferenceDTO'
description: A filter that uses an existing selection concept in Visier.
memberSet:
allOf:
- $ref: '#/components/schemas/dataservices.query.MemberFilterDTO'
description: A filter that includes or excludes dimension members.
cohort:
allOf:
- $ref: '#/components/schemas/dataservices.query.CohortFilterDTO'
description: A filter that identifies a population at a specific time.
description: A QueryFilter selects specific data points within a population.
dataservices.query.QueryMemberMapPropertyDTO:
type: object
properties:
memberMap:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A member map and its qualifying path to query.
targetDimensionName:
type: string
description: The name of the member map's dimension that you want to query. The member selection is based on this dimension.
description: A QueryMemberMapProperty defines an existing member map and its dimension to query.
dataservices.query.QueryDimensionMemberSelectionDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A dimension and its qualifying path to query.
members:
type: array
items:
$ref: '#/components/schemas/dataservices.common.DimensionMemberReferenceDTO'
description: A collection of dimension members to select in the query. This must contain at least one member.
description: A QueryDimensionMemberSelection defines dimension members to select in the query.
dataservices.query.SnapshotQueryExecutionDTO:
type: object
properties:
source:
allOf:
- $ref: '#/components/schemas/dataservices.query.ListQuerySourceDTO'
description: The source data that you want to query.
columns:
type: array
items:
$ref: '#/components/schemas/dataservices.query.PropertyColumnDTO'
description: The columns to include in the result. This must contain at least one column.
sortOptions:
type: array
items:
$ref: '#/components/schemas/dataservices.query.SortOptionDTO'
description: The index and direction to sort a column in the `columns` array.
filters:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryFilterDTO'
description: The filters of this query. Omit `filters` if no filtering is required.
timeIntervals:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryTimeIntervalsDTO'
description: The time intervals to query.
parameterValues:
type: array
items:
$ref: '#/components/schemas/dataservices.query.QueryParameterValueDTO'
description: The parameter values for either member or numeric parameters.
options:
allOf:
- $ref: '#/components/schemas/dataservices.query.SnapshotQueryExecutionOptionsDTO'
description: Additional instructions for your query, such as a calendar type or conversion information.
dataservices.query.CohortFilterDTO:
type: object
properties:
keyGroup:
allOf:
- $ref: '#/components/schemas/dataservices.query.KeyGroupFilterDTO'
description: A key group is a collection of filters that define the shape of the analysis population.
exclude:
type: boolean
description: If true, the population is defined by those excluded by the filters. Default is false.
timeInterval:
allOf:
- $ref: '#/components/schemas/dataservices.query.QueryTimeIntervalDTO'
description: The time at which to apply the key group, such as a specific day or period of months.
description: "Use a cohort filter to define a population as it existed during a specific time period.\n Cohort filters allow you to define a population in terms of a collection of filters, known as a key group.\n The cohort's defined time interval is independent of the query's time. The cohort's time interval is the\n time at which the key group should be applied.\n Cohorts are typically used to follow populations and understand changes to the population over time,\n such as promotion and resignation rates."
dataservices.query.SubjectMemberSetParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique ID of the subject member set parameter.
keyNamePaths:
type: array
items:
$ref: '#/components/schemas/dataservices.query.SubjectMemberSetParameterValueDTO_NamePathDTO'
description: The name path keys for the subject member set parameter; for example, `["Java"]`.
valueNamePaths:
type: array
items:
$ref: '#/components/schemas/dataservices.query.SubjectMemberSetParameterValueDTO_ListOfNamePathDTO'
description: The name path values for each subject member set parameter key; for example, `["5.0"]`.
description: The value for a subject member set parameter.
google.protobuf.Any:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
dataservices.query.InternalQueryExecutionOptionsDTO:
type: object
properties:
sparseHandlingMode:
enum:
- ALLOW
- DISALLOW
- FORCE
type: string
format: enum
alignTimeAxisToPeriodEnd:
type: boolean
description: "If true, shifts the time axis members back by one millisecond.\n Shifting the time axis members back by one millisecond makes them valid at the end of the period instead of at the start of the next period.\n This aligns the returned data timestamps with the timestamps in the Visier application.\n\n Example: If the timestamps are originally [`2019-06-01T00:00:00.000Z`, `2019-05-01T00:00:00.000Z`],\n then `alignTimeAxisPeriodEnd` turns the timestamps into [`2019-05-31T23:59:59.999Z`, `2019-04-30T23:59:59.999Z`].\n\n Example: If the timestamps are originally [`2019-05-01T00:00:00.000Z/2019-06-01T00:00:00.000Z`, `2019-04-01T00:00:00.000Z/2019-05-01T00:00:00.000Z`],\n then `alignTimeAxisPeriodEnd` turns the timestamps into [`2019-05-01T00:00:00.000Z/2019-05-31T23:59:59.999Z`, `2019-04-01T00:00:00.000Z/2019-04-30T23:59:59.999Z`]."
description: Query options for Visier use. Not supported for customer or partner use.
dataservices.query.QueryAxisSortDTO:
type: object
properties:
sortType:
enum:
- CONFIGURED
- METRIC_VALUE
type: string
description: "The order in which to return axis members in the response. Valid values:\n - `CONFIGURED`: Sorts axis members by their configuration:\n - For parent-child dimensions, sorts axis members alphabetically by name.\n - For all other dimensions, sorts axis members by their configured order in Studio.\n - Unknown members are always placed at the end of the axis.\n - `METRIC_VALUE`: Sorts axis members by their metric values. Applicable if there is only one query axis and only one time axis member."
format: enum
sortDirection:
enum:
- SORT_ASCENDING
- SORT_DESCENDING
type: string
description: "The direction in which to return axis members in the response. Valid values:\n - `SORT_ASCENDING`: Sorts axis members in ascending order.\n - `SORT_DESCENDING`: Sorts axis members in descending order."
format: enum
description: Sort the axis members returned in the response by type and direction.
dataservices.query.QueryDimensionLeafSelectionDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A dimension and its qualifying path to query.
description: "A QueryDimensionLeafSelection allows you to define a member set consisting exclusively\n of leaf-level members for the given dimension. Leaf members are those members that have\n no descendents. A member may be a leaf member regardless of the level it is positioned at.\n This member selection option, excludes data members."
dataservices.query.AggregationQuerySourceMetricDTO:
type: object
properties:
columnName:
type: string
description: The column name in the CSV file. Default is to use id as the column name.
id:
type: string
description: "The unique ID of the metric.\n If `columnName` is omitted, `id` is the column name in the CSV file."
formula:
type: string
description: "An ad-hoc metric formula. The response returns the results of the aggregate.\n See the formula dictionary in Visier to find functions and objects you can use in a formula."
qualifyingPath:
type: string
description: "The base qualifying path to prefix the axes and filters' qualifying paths with.\n You must specify the qualifying path on a metric if the convergent analytic object of the metric doesn't match the\n starting object in the qualifying paths of the axes and filters.\n\n For example, consider a multi-metric query that contains metrics that count the number of applicants and requisitions,\n grouped by the country of the recruiter's direct manager. The following sample shows how to use qualifyingPath to specify\n the object reference traversal path from each metric's convergent analytic object to the start of the path for the axes.\n In this example, there is only one convergent analytic object.\n ```\n \"source\": {\n \"metrics\": {\n \"columns\": [\n {\n \"id\": \"employeeCount\"\n },\n {\n \"id\": \"applicantCount\",\n \"qualifyingPath\": \"Applicant.Requisition.Recruiter\"\n },\n {\n \"id\": \"requisitionCount\",\n \"qualifyingPath\": \"Requisition.Recruiter\"\n }\n ]\n }\n },\n \"axes\": [\n {\n \"dimensionLevelSelection\": {\n \"dimension\": {\n \"name\": \"Location\",\n \"qualifyingPath\": \"Employee.Direct_Manager\"\n },\n \"levelIds\": [\n \"Location_1\"\n ]\n }\n }\n ]\n ```\n **Note:**\n * `employeeCount` doesn't need a `qualifyingPath` because it's already convergent with the start of the axis path.\n * The metrics' qualifying paths must provide the reference name that resolves to the first object of the axis' qualifying path as their last path segment. In this case, Recruiter is a named reference pointing to Employee. The final qualifying paths for the metrics are:\n * `employeeCount`: Employee.Direct_Manager\n * `applicantCount`: Applicant.Requisition.Recruiter.Direct_Manager\n * `requisitionCount`: Requisition.Recruiter.Direct_Manager"
description: The column definition for a single metric within a `metrics` query.
dataservices.query.QueryAxisLimitDTO:
type: object
properties:
limitType:
enum:
- FIRST_N
- LAST_N
type: string
description: "The type of limit to apply to the axis. Valid values:\n - `FIRST_N`: Limits the axis to the first N members.\n - `LAST_N`: Limits the axis to the last N members."
format: enum
n:
type: integer
description: If `limitType` is defined, the number of axis members to include. `n` must be at least `1`. If less than `1`, no limit is applied.
format: int32
showOthers:
type: boolean
description: If `true`, includes an `Others` member that aggregates all members not included in the limited set. Default is `false`.
description: Limit the number of axis members returned in the response.
dataservices.query.QueryExecutionErrorDetailsDTO:
type: object
properties:
objectType:
type: string
description: Query request object type.
queryIndex:
type: integer
description: The position of the query within the request query list.
format: int32
columnIndex:
type: integer
description: The position of the column within the request column list.
format: int32
error:
type: string
description: The details of the error.
description: The details of a error that occurred during query execution.
dataservices.query.QueryDimensionDataMemberSelectionDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/dataservices.datamodel.DimensionReferenceDTO'
description: A dimension and its qualifying path to query.
description: "A QueryDimensionLeafSelection allows you to define a member set consisting exclusively\n of leaf-level, including data, members for the given dimension. Leaf members are those members that have\n no descendents. A member may be a leaf member regardless of the level it is positioned at."
Status:
type: object
properties:
localizedMessage:
type: string
description: Localized error message describing the root cause of the error.
code:
type: string
description: Error classification.
message:
type: string
description: Not used.
rci:
type: string
description: Optional root cause identifier.
userError:
type: boolean
description: Indicates whether the error is a user error.
description: The response structure for errors.
dataservices.query.SortOptionDTO:
type: object
properties:
columnIndex:
type: integer
description: The index of the column of the list query, staring from 0.
format: int32
sortDirection:
enum:
- SORT_ASCENDING
- SORT_DESCENDING
type: string
description: The sort direction.
format: enum
description: Sort option for a column of a list query.
dataservices.query.SnapshotQueryExecutionOptionsDTO:
type: object
properties:
limit:
type: integer
description: "The maximum number of entries to return. Default is to return all entries. If `page` is defined but\n limit is not defined, limit will be set to a default value of 1000."
format: int32
queryMode:
enum:
- DEFAULT
- FILL
- FAIL
type: string
description: Determines how the query should handle column definitions that the query is unable to resolve. Default is DEFAULT.
format: enum
omitHeader:
type: boolean
description: "Option to omit the header from the result.\n If true, queryMode must be either FILL or FAIL.\n Default is false."
calendarType:
enum:
- TENANT_CALENDAR
- GREGORIAN_CALENDAR
type: string
description: "The calendar type to use. This will be used for all time calculations unless explicitly overridden in\n the calculation itself. Default is TENANT_CALENDAR.
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-dataquery-api-openapi.yml