# Adaptive cards

**Base URL:** `https://{tenant}.{region}.qlikcloud.com`

## Table of Contents

| Method | Path | Description |
|--------|------|-------------|
| `GET` | [`/api/analytics/discovery-agent/adaptive-cards`](#get-apianalyticsdiscovery-agentadaptive-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. |

## API Reference

### GET /api/analytics/discovery-agent/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.


- **Rate Limit:** Tier 1 (1000 requests per minute)

#### Query Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `analysisTypes` | string[] | No | Filter by analysis type. Repeat the parameter to include multiple types. When this parameter is present, all matching results are returned regardless of ranking.  Enum: "recordHigh", "recordLow", "aboveModel", "belowModel", "spikesUp", "spikesDown", "newBaseLine", "trendChanges" |
| `appIds` | string[] | No | 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` | string[] | No | 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` | string[] | No | Filter by category IDs from the business glossary. Category filtering is not currently applied to the result set. |
| `comparisonPeriods` | string[] | No | Filter by comparison period. Example values: `D`, `W`, `M`, `Q`, `Y`. When this parameter is present, all matching results are returned regardless of ranking.  Enum: "D", "W", "M", "Q", "Y" |
| `dimensions` | string[] | No | Filter by dimension(s). Matching is case-sensitive; leading and trailing whitespace will be trimmed. Repeat the parameter to supply multiple dimensions. |
| `limit` | integer | No | The maximum number of resources to return for a request. The limit must be an integer between 1 and 100 (inclusive). |
| `measures` | string[] | No | Filter by measure(s). Matching is case-sensitive; leading and trailing whitespace will be trimmed. Repeat the parameter to supply multiple measures. |
| `metricIds` | string[] | No | Filter by metric ID. Repeat the parameter to supply multiple IDs. When omitted, returns cards for all metrics visible to the caller. |
| `next` | integer | No | The numeric offset to the next page of resources. Provide either the next or prev parameter, but not both. |
| `prev` | integer | No | The numeric offset to the previous page of resources. Provide either the next or prev parameter, but not both. |
| `sort` | string | No | The field to sort by, with +/- prefix indicating sort order Enum: "creationTime", "+creationTime", "-creationTime" |
| `timeRangeEnd` | string | No | Exclusive upper bound for filtering by analysis result end time. Use ISO 8601 format. |
| `timeRangeStart` | string | No | Inclusive lower bound for filtering by analysis result end time. Use ISO 8601 format. |
| `type` | string | No | Filter by Adaptive Card category. When omitted, cards from all categories are returned. Enum: "measures", "dimensions", "breakdowns" |

#### Header Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | JWT containing tenant credentials. |

#### Responses

##### 200

Returns the requested Adaptive Cards.

**Content-Type:** `application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | Yes | Adaptive Card |
| `links` | object | Yes |  |
| `inAppMetrics` | object[] | No |  |

<details>
<summary>Properties of `links`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `next` | object | No |  |
| `prev` | object | No |  |
| `self` | object | No |  |

<details>
<summary>Properties of `next`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `href` | string | No |  |

</details>

<details>
<summary>Properties of `prev`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `href` | string | No |  |

</details>

<details>
<summary>Properties of `self`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `href` | string | No |  |

</details>

</details>

<details>
<summary>Properties of `inAppMetrics`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The ID of the in-app metric in the database. |
| `appId` | string | Yes | The ID of the app. |
| `links` | object | Yes |  |
| `status` | integer | Yes | Status of the in app metrics (0 - inactive, 1 - active). Enum: 0, 1 |
| `userId` | string | Yes | The ID of the user who created the in-app-metric. |
| `tenantId` | string | Yes | The ID of the tenant who owns the in-app metric. |
| `definition` | object | Yes |  |
| `updateTime` | string | Yes | The time when the in-app metric was last updated. |
| `creationTime` | string | Yes | The time when the in-app metric was created. |

<details>
<summary>Properties of `links`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `self` | object | No |  |

<details>
<summary>Properties of `self`</summary>

_Properties truncated due to depth limit._

</details>

</details>

<details>
<summary>Properties of `definition`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `status` | integer | No | Status of the in app metrics (0 - inactive, 1 - active). Enum: 0, 1 |
| `measure` | string | Yes |  |
| `upwardIs` | integer | No | Indicates whether an increase in the metric is considered neutral (0), positive (1) or negative (-1). Enum: 0, 1, -1 |
| `dimension` | string | Yes |  |
| `categories` | object[] | No |  |
| `glossaryId` | string | No | The ID of the glossary that the in-app metric belongs to. |
| `description` | string | No | A description of the in-app metric. |
| `analysisTypes` | string[] | Yes | Type of analysis performed on the in-app metric. Enum: "recordHigh", "recordLow", "aboveModel", "belowModel", "spikesUp", "spikesDown", "newBaseLine", "trendChanges" |
| `comparisonPeriods` | string[] | No | Comparison period for the analysis. Enum: "D", "W", "M", "Q", "Y" |
| `breakDownDimensions` | object[] | No | 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. |
| `nextExecutionOffset` | integer | No | Number of days to offset the execution of analyses for this aggregation period. |

<details>
<summary>Properties of `categories`</summary>

_Properties truncated due to depth limit._

</details>

<details>
<summary>Properties of `breakDownDimensions`</summary>

_Properties truncated due to depth limit._

</details>

</details>

</details>

##### 400

Bad request.

**Content-Type:** `application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | object[] | No |  |

<details>
<summary>Properties of `errors`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'. |
| `title` | string | Yes |  |
| `detail` | string | No |  |

</details>

##### 401

Unauthorized, JWT invalid or not provided.

**Content-Type:** `application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | object[] | No |  |

<details>
<summary>Properties of `errors`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'. |
| `title` | string | Yes |  |
| `detail` | string | No |  |

</details>

##### 403

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

**Content-Type:** `application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | object[] | No |  |

<details>
<summary>Properties of `errors`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'. |
| `title` | string | Yes |  |
| `detail` | string | No |  |

</details>

##### 500

Internal server error.

**Content-Type:** `application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | object[] | No |  |

<details>
<summary>Properties of `errors`</summary>

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'. |
| `title` | string | Yes |  |
| `detail` | string | No |  |

</details>

#### Examples

**JavaScript:**

```javascript
// 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:**

```bash
# qlik-cli has not implemented support for GET /api/analytics/discovery-agent/adaptive-cards yet.
```

**cURL:**

```bash
curl "https://{tenant}.{region}.qlikcloud.com/api/analytics/discovery-agent/adaptive-cards" \
-H "Authorization: Bearer <access_token>"
```

**Example Response:**

```json
{
  "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"
    }
  ]
}
```

---