Adaptive cards

Download OpenAPI spec

Generate adaptive cards for all metrics

Retrieves Adaptive Card(s) in JSON format. Support fetching of a single card by metric ID or multiple cards by a list of metric IDs. Support filtering by app IDs, measures, dimensions, categories, breakdown dimension, analysis types and triggered time range. When filtering by measures, use appIds parameter to scope results to specific apps, as the same measure expression can exist across multiple apps.

Ranking behaviour: When the endpoint is called without any filter parameters (bare GET /adaptive-cards), only the top-ranked result per metric (rank ≤ 1) or results without a rank field are returned. When any DB-reaching filter is supplied (metricIds, dimensions, measures, appIds, breakdowns, analysisTypes, comparisonPeriods, timeRangeStart, timeRangeEnd), ranking is not applied and all matching results are returned so that explicit filters are never silently constrained by rank.

Facts

Rate limit Tier 1 (1000 requests per minute)

Header Parameters

  • Authorizationstring
    Required

    JWT containing tenant credentials.

Query Parameters

  • analysisTypesarray of strings

    Filter by analysis types. Repeat parameter to include multiple types (results may match any of the provided types). When this parameter is present, the rank filter is disabled and all matching analysis types are returned regardless of rank.

    Values may be any of: "recordHigh""recordLow""aboveModel""belowModel""spikesUp""spikesDown""newBaseLine""trendChanges"

  • appIdsarray of strings

    Filter by app ID(s). Use this to scope results to specific apps. When combined with measures, returns only cards matching BOTH criteria (AND logic). Repeat the parameter to supply multiple app IDs (OR logic within appIds).

    Recommendation: Use consistent parameter order for better HTTP cache hit rates:

    1. . appIds (if present)
    2. . measures (if present)
    3. . other filters
    4. . pagination (limit, next, prev)

    Example - One app, multiple measures: ?appIds=app-123&measures=Sum(Sales)&measures=Avg(Revenue)&measures=Count(Orders)

    Example - Multiple apps, one measure: ?appIds=app-retail&appIds=app-wholesale&measures=Sum(Sales)

    Example - Multiple apps, multiple measures: ?appIds=app-sales&appIds=app-hr&measures=Sum(Revenue)&measures=Avg(Salary)

  • breakdownsarray of strings

    Filter by one or more breakdown selections in the form dimension:value (example Region:EMEA). Values are selected from the UI dropdown — not free text — and should match available dimension/value pairs. Repeat the parameter to supply multiple breakdowns; results match any of the provided breakdown pairs.

  • categoriesarray of strings

    List of category ids from the business glossary. Parsed by the API but not applied to the DB filter in the current implementation.

  • comparisonPeriodsarray of strings

    Filter by comparison (aggregation) periods. Example values: D, W, M, Q, Y. When this parameter is present, the rank filter is disabled and all matching periods are returned regardless of rank.

    Values may be any of: "D""W""M""Q""Y"

  • dimensionsarray of strings

    Filter by dimension(s). Matching is case-sensitive; leading and trailing whitespace will be trimmed. Repeat the parameter to supply multiple dimensions.

  • limitinteger

    The maximum number of resources to return for a request. The limit must be an integer between 1 and 100 (inclusive).

    minimum = 1, maximum = 100, default = 10, format = int32, default = 10

  • measuresarray of strings

    Filter by measure(s). Matching is case-sensitive; leading and trailing whitespace will be trimmed. Repeat the parameter to supply multiple measures.

  • metricIdsarray of strings

    Comma-separated list of metric IDs to return Adaptive Cards for. When omitted the endpoint may return cards for multiple metrics visible to the tenant.

  • nextinteger

    The numeric offset to the next page of resources. Provide either the next or prev parameter, but not both.

    format = int32

  • previnteger

    The numeric offset to the previous page of resources. Provide either the next or prev parameter, but not both.

    format = int32

  • sortstring

    The field to sort by, with +/- prefix indicating sort order

    Can be one of: "creationTime""+creationTime""-creationTime"

    default = "+creationTime"

  • timeRangeEndstring

    Exclusive upper bound for analysis result end time. Use ISO 8601 format (example: 2023-10-31T00:00:00.000Z). The store applies this as endTime < timeRangeEnd.

    format = "date-time"

  • timeRangeStartstring

    Inclusive lower bound for analysis result end time. Use ISO 8601 format (example: 2023-10-01T00:00:00.000Z). The store applies this as endTime >= timeRangeStart.

    format = "date-time"

  • typestring

    Optional filter to request only one category: measures, dimensions, or breakdowns. When omitted, all categories are returned.

    Can be one of: "measures""dimensions""breakdowns"

Responses

200

Expected response to a valid request.

  • application/jsonobject
    Show application/json properties
    • dataarray of objects
      Required

      Adaptive card

    • linksobject
      Required
      Show links properties
      • nextobject
        Show next properties
        • hrefstring

          format = "uri"

      • prevobject
        Show prev properties
        • hrefstring

          format = "uri"

      • selfobject
        Show self properties
        • hrefstring

          format = "uri"

    • inAppMetricsarray of objects
      Show inAppMetrics properties
      • idstring
        Required

        The ID of the in-app metric in the database.

      • appIdstring
        Required

        The ID of the app.

      • linksobject
        Required
        Show links properties
        • selfobject
          Show self properties
          • hrefstring

            format = "uri"

      • statusinteger
        Required

        Status of the in app metrics (0 - inactive, 1 - active).

        Can be one of: 01

      • userIdstring
        Required

        The ID of the user who created the in-app-metric.

      • tenantIdstring
        Required

        The ID of the tenant who owns the in-app metric.

      • definitionobject
        Required
        Show definition properties
        • namestring
          Required
        • statusinteger

          Status of the in app metrics (0 - inactive, 1 - active).

          Can be one of: 01

        • measurestring
          Required
        • upwardIsinteger

          Indicates whether an increase in the metric is considered neutral (0), positive (1) or negative (-1).

          Can be one of: 01-1

        • dimensionstring
          Required
        • categoriesarray of objects
          Show categories properties
          • glossaryIdstring

            The ID of the glossary that the category belongs to.

          • categoryIdsarray of strings

            The IDs of the categories.
        • glossaryIdstring

          The ID of the glossary that the in-app metric belongs to.

        • descriptionstring

          A description of the in-app metric.

        • analysisTypesarray of strings
          Required

          Type of analysis performed on the in-app metric.

          Values may be any of: "recordHigh""recordLow""aboveModel""belowModel""spikesUp""spikesDown""newBaseLine""trendChanges"

        • comparisonPeriodsarray of strings

          Comparison period for the analysis.

          Values may be any of: "D""W""M""Q""Y"

        • breakDownDimensionsarray of objects

          Breakdown dimension with filtering capabilities.

          • dimension is required.
          • values and filter are optional. If both are omitted (or values is empty and filter is null), the API interprets this as "analyze all values" for the given dimension.
          Show breakDownDimensions properties
          • filterobject

            Filter configuration for a breakdown dimension

            Show filter properties
            • typestring
              Required

              Type of breakdown filter

              Can be one of: "values""search""condition""topBottom"

            • searchobject

              Search-based filtering configuration. If searchString is empty or not provided, all dimension values will be analyzed (no filtering applied).

              Show search properties
              • searchTypestring
                Required

                Search operation type

                Can be one of: "contains""exactMatch""startsWith""endsWith""beginningOfWord"

              • searchStringstring

                String to search for. If empty, all dimension values are analyzed.
            • valuesarray of strings

              List of values to filter by (used when type is Values)

            • excludeboolean

              When set to true, the filter values are excluded from analysis instead of included.

              • If exclude is false or omitted, only the matched values are analyzed (max 50).
              • If exclude is true, all dimension values EXCEPT the matched values are analyzed (max 50).

              default = false

            • conditionobject

              Condition-based filtering configuration. Supports single comparisons (>, >=, <, <=) and range comparisons (> <, >= <=).

              Single Comparisons:

              • Compare type: Uses value (Fixed) or aggregation+field (Calculated)
              • General type: Uses aggregation+field and either value (Fixed) or aggregation2+field2 (Calculated)

              Range Comparisons (> < or >= <=):

              • Compare type: Uses fromValue+toValue (Fixed) or fromAggregation+fromField+toAggregation+toField (Calculated)
              • General type: Uses aggregation+field plus either fromValue+toValue (Fixed) or fromAggregation+fromField+toAggregation+toField (Calculated)
              Show condition properties
              • fieldstring

                Primary field for calculated values

              • valuenumber

                Fixed numeric value (used by single comparisons with Compare.Fixed and General.Fixed)

              • field2string

                Additional field used only by General.Calculated for single comparisons

              • toFieldstring

                Upper bound field for range comparisons with Calculated value type (used with > < or >= <=)

              • toValuenumber

                Upper bound value for range comparisons with Fixed value type (used with > < or >= <=)

              • fromFieldstring

                Lower bound field for range comparisons with Calculated value type (used with > < or >= <=)

              • fromValuenumber

                Lower bound value for range comparisons with Fixed value type (used with > < or >= <=)

              • valueTypestring

                Whether the value is calculated or fixed

                Can be one of: "calculated""fixed"

              • aggregationstring

                Aggregation operation type

                Can be one of: "sum""avg""count""max""min"

              • aggregation2string

                Aggregation operation type

                Can be one of: "sum""avg""count""max""min"

              • conditionTypestring
                Required

                Condition evaluation type

                Can be one of: "general""compare"

              • toAggregationstring

                Aggregation operation type

                Can be one of: "sum""avg""count""max""min"

              • comparisonTypestring
                Required

                Comparison operation type

                Can be one of: ">"">=""<""<=""> <"">= <="

              • fromAggregationstring

                Aggregation operation type

                Can be one of: "sum""avg""count""max""min"

            • topBottomobject

              Top/bottom filtering configuration

              Show topBottom properties
              • typestring
                Required

                Whether to select top or bottom values

                Can be one of: "top""bottom"

              • unitstring
                Required

                Unit for top/bottom selection

                Can be one of: "numerical""percentage"

              • numberinteger
                Required

                Number of top/bottom values to select
          • valuesarray of strings

            List of values (kept for backward compatibility)

          • dimensionstring
            Required

            The dimension name
        • nextExecutionOffsetinteger

          Number of days to offset the execution of analyses for this aggregation period.
      • updateTimestring
        Required

        The time when the in-app metric was last updated.

      • creationTimestring
        Required

        The time when the in-app metric was created.

400

Bad request.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects
      Show errors properties
      • codestring
        Required

        The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'.

      • titlestring
        Required
      • detailstring

401

Unauthorized, JWT invalid or not provided.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects
      Show errors properties
      • codestring
        Required

        The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'.

      • titlestring
        Required
      • detailstring

403

Forbidden, the requesting JWT does not allow for retrieval of in-app metrics (error code: OWL-003).

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects
      Show errors properties
      • codestring
        Required

        The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'.

      • titlestring
        Required
      • detailstring

500

Internal server error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects
      Show errors properties
      • codestring
        Required

        The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'.

      • titlestring
        Required
      • detailstring
GET /api/analytics/discovery-agent/adaptive-cards 
// qlik-api has not implemented support for `GET /api/analytics/discovery-agent/adaptive-cards` yet.
// In the meantime, you can use fetch like this:


const response = await fetch(
  '/api/analytics/discovery-agent/adaptive-cards',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  },
)
# qlik-cli has not implemented support for GET /api/analytics/discovery-agent/adaptive-cards yet.
curl "https://{tenant}.{region}.qlikcloud.com/api/analytics/discovery-agent/adaptive-cards" \
-H "Authorization: Bearer <access_token>"

Example Response

{
  "data": [
    {}
  ],
  "links": {
    "next": {
      "href": "http://example.com"
    },
    "prev": {
      "href": "http://example.com"
    },
    "self": {
      "href": "http://example.com"
    }
  },
  "inAppMetrics": [
    {
      "id": "67cab2cf3d74cae279940b99",
      "appId": "9b89de1e-9a1b-11ef-9974-563d08542bef",
      "links": {
        "self": {
          "href": "http://example.com"
        }
      },
      "status": 1,
      "userId": "FyPG6xWp6prDU6BXQ3g7LY9gWR_YRkkx",
      "tenantId": "efSCcpNYuayTysONkUcE3F80zYQ_LV9w",
      "definition": {
        "name": "Profit by region Europe",
        "status": 1,
        "measure": "Sum({<Region='Europe'>} Profit)",
        "upwardIs": 1,
        "dimension": "ShipDate",
        "categories": [
          {
            "glossaryId": "fe7df4a8-abb4-42da-95e7-4ee8db22a7cb",
            "categoryIds": [
              "6db0fd8e-2115-4ac6-8d51-1729adbc4cfd"
            ]
          }
        ],
        "glossaryId": "5a7482f5-892a-4194-9f48-366ccb48a1e7",
        "description": "This metric shows the profit by region in Europe.",
        "analysisTypes": [
          "recordHigh",
          "aboveModel",
          "spikesUp"
        ],
        "comparisonPeriods": [
          "D",
          "W",
          "M",
          "Q",
          "Y"
        ],
        "breakDownDimensions": [
          {
            "filter": {
              "type": "values",
              "values": [
                "Europe",
                "Asia"
              ]
            },
            "values": [
              "Europe",
              "Asia"
            ],
            "dimension": "Region"
          }
        ],
        "nextExecutionOffset": 7
      },
      "updateTime": "2023-10-01T12:00:00Z",
      "creationTime": "2023-10-01T12:00:00Z"
    }
  ]
}