Adaptive cards

Download OpenAPI spec

List Adaptive Cards

Retrieves Adaptive Cards for in-app metrics. Supports fetching a single card by metric ID or multiple cards by a list of metric IDs. Supports filtering by app IDs, measures, dimensions, categories, breakdown dimensions, analysis types, and triggered time range. When filtering by measures, use the appIds parameter to scope results to specific apps, as the same measure expression can exist across multiple apps.

When called without any filter parameters, only the top-ranked result per metric is returned. When any filtering parameter is supplied (metricIds, dimensions, measures, appIds, breakdowns, analysisTypes, comparisonPeriods, timeRangeStart, timeRangeEnd), ranking is not applied and all matching results are returned.

Facts

Rate limit Tier 1 (1000 requests per minute)

Header Parameters

  • Authorization string
    Required

    JWT containing tenant credentials.

Query Parameters

  • analysisTypes array of strings

    Filter by analysis type. Repeat the parameter to include multiple types. When this parameter is present, all matching results are returned regardless of ranking.

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

  • appIds array 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)

  • breakdowns array 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.

  • categories array of strings

    Filter by category IDs from the business glossary. Category filtering is not currently applied to the result set.

  • comparisonPeriods array of strings

    Filter by comparison period. Example values: D, W, M, Q, Y. When this parameter is present, all matching results are returned regardless of ranking.

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

  • dimensions array of strings

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

  • limit integer

    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

  • measures array of strings

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

  • metricIds array of strings

    Filter by metric ID. Repeat the parameter to supply multiple IDs. When omitted, returns cards for all metrics visible to the caller.

  • next integer

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

    format = int32

  • prev integer

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

    format = int32

  • sort string

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

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

    default = "+creationTime"

  • timeRangeEnd string

    Exclusive upper bound for filtering by analysis result end time. Use ISO 8601 format.

    format = "date-time"

  • timeRangeStart string

    Inclusive lower bound for filtering by analysis result end time. Use ISO 8601 format.

    format = "date-time"

  • type string

    Filter by Adaptive Card category. When omitted, cards from all categories are returned.

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

Responses

200

Returns the requested Adaptive Cards.

  • application/json object
    Show application/json properties
    • data array of objects
      Required

      Adaptive Card

    • links object
      Required
      Show links properties
      • next object
        Show next properties
        • href string

          format = "uri"

      • prev object
        Show prev properties
        • href string

          format = "uri"

      • self object
        Show self properties
        • href string

          format = "uri"

    • inAppMetrics array of objects
      Show inAppMetrics properties
      • id string
        Required

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

      • appId string
        Required

        The ID of the app.

      • links object
        Required
        Show links properties
        • self object
          Show self properties
          • href string

            format = "uri"

      • status integer
        Required

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

        Can be one of: 01

      • userId string
        Required

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

      • tenantId string
        Required

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

      • definition object
        Required
        Show definition properties
        • name string
          Required
        • status integer

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

          Can be one of: 01

        • measure string
          Required
        • upwardIs integer

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

          Can be one of: 01-1

        • dimension string
          Required
        • categories array of objects
          Show categories properties
          • glossaryId string

            The ID of the glossary that the category belongs to.

          • categoryIds array of strings

            The IDs of the categories.
        • glossaryId string

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

        • description string

          A description of the in-app metric.

        • analysisTypes array 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"

        • comparisonPeriods array of strings

          Comparison period for the analysis.

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

        • breakDownDimensions array 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
          • filter object

            Filter configuration for a breakdown dimension

            Show filter properties
            • type string
              Required

              Type of breakdown filter

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

            • search object

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

              Show search properties
              • searchType string
                Required

                Search operation type

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

              • searchString string

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

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

            • exclude boolean

              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

            • condition object

              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
              • field string

                Primary field for calculated values

              • value number

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

              • field2 string

                Additional field used only by General.Calculated for single comparisons

              • toField string

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

              • toValue number

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

              • fromField string

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

              • fromValue number

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

              • valueType string

                Whether the value is calculated or fixed

                Can be one of: "calculated""fixed"

              • aggregation string

                Aggregation operation type

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

              • aggregation2 string

                Aggregation operation type

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

              • conditionType string
                Required

                Condition evaluation type

                Can be one of: "general""compare"

              • toAggregation string

                Aggregation operation type

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

              • comparisonType string
                Required

                Comparison operation type

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

              • fromAggregation string

                Aggregation operation type

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

            • topBottom object

              Top/bottom filtering configuration

              Show topBottom properties
              • type string
                Required

                Whether to select top or bottom values

                Can be one of: "top""bottom"

              • unit string
                Required

                Unit for top/bottom selection

                Can be one of: "numerical""percentage"

              • number integer
                Required

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

            List of values (kept for backward compatibility)

          • dimension string
            Required

            The dimension name
        • nextExecutionOffset integer

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

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

      • creationTime string
        Required

        The time when the in-app metric was created.

400

Bad request.

  • application/json object
    Show application/json properties
    • errors array of objects
      Show errors properties
      • code string
        Required

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

      • title string
        Required
      • detail string

401

Unauthorized, JWT invalid or not provided.

  • application/json object
    Show application/json properties
    • errors array of objects
      Show errors properties
      • code string
        Required

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

      • title string
        Required
      • detail string

403

Forbidden, the requesting JWT does not allow retrieval of Adaptive Cards (error code: OWL-003).

  • application/json object
    Show application/json properties
    • errors array of objects
      Show errors properties
      • code string
        Required

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

      • title string
        Required
      • detail string

500

Internal server error.

  • application/json object
    Show application/json properties
    • errors array of objects
      Show errors properties
      • code string
        Required

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

      • title string
        Required
      • detail string
GET /api/analytics/discovery-agent/adaptive-cards 
import { createQlikApi } from '@qlik/api'


const qlik = createQlikApi({
  hostConfig: {
    host: 'https://{tenant}.{region}.qlikcloud.com',
    apiKey: '<access-token>',
  },
})


await qlik.analytics.discoveryAgent.adaptiveCards.getAdaptiveCards(
  {},
)
qlik analytics discovery-agent adaptive-card ls
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"
    }
  ]
}