> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/metrics-tools/qualtrics/how-to-use-qualtrics-in-a-metric.md).

# How to use Qualtrics in a metric

Turn the responses to a Qualtrics survey question into a live card on any journey map.

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* The Qualtrics integration is set up at the account level. See [How to set up the Qualtrics integration](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration.md).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Qualtrics metric

You can create a Qualtrics metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

<figure><img src="/files/gy58S461JBtzpnJ7PEM6" alt="Journey map Add card picker open on a card slot, showing a Text quick-select row, the Basic Cards group (Image, Stage, Icons, Slider), and the Advanced Cards group (Embed, Planning, Metric, Link journey map)."><figcaption><p>Add card picker on a journey map, Metric under Advanced cards</p></figcaption></figure>

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Open the Add metric form**

In the workspace sidebar, click **Metrics**, then **+ Create metric**. The **Add metric** form opens with the two-column layout: **Metric data source** on the left and **Default card preview** on the right.

<figure><img src="/files/9gBD6PbP1ZTxOK0LDhlh" alt="Add metric page in the empty state. Left column shows the Metric data source heading with Name, Source, Type, and Metric tags fields. Right column shows the Default card preview with a Show Preview tile, a chart-type chip strip, and Chart heading and Chart subheading inputs."><figcaption><p>Add metric, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the metric and pick Qualtrics as the source**

Type a name that describes what the metric shows (for example, `Customer satisfaction score`). In **Source**, pick **Qualtrics**.

<figure><img src="/files/jvZaTDGW6c2tmuvhM5ju" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, all sources listed</p></figcaption></figure>

If you see a pink **Qualtrics setup required** block instead of the survey fields, the integration isn't connected for this account yet. Click **Setup Qualtrics** in the block and follow [How to set up the Qualtrics integration](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration.md) before continuing.
{% endstep %}

{% step %}
**Pick a metric type**

Open the **Type** dropdown and pick a type. Qualtrics supports **Series**, **Number**, and **Comparison**. The four Qualtrics fields only appear after you pick a type, and they're the same set whichever type you choose.

<figure><img src="/files/Sg6SLjo8QmncCscEFlWH" alt="Type dropdown open on the Add metric form with Source set to Qualtrics. The dropdown lists Series, Number, and Comparison, each with a small icon to the left of the label."><figcaption><p>Type dropdown, Series / Number / Comparison for Qualtrics</p></figcaption></figure>

This guide uses **Series**, which plots the responses as a chart. For which type fits a single headline value or a side-by-side comparison instead, see [How to choose a metric type](/metrics/how-to-choose-a-metric-type.md).
{% endstep %}

{% step %}
**Map the Qualtrics fields**

Four fields drive what the metric pulls: **Survey**, **Question**, **Group by**, and **Calculation**. Fill them top to bottom, because each one enables the next.

* Pick the survey under **Survey**. Only surveys the connected Qualtrics account can access appear in the list.
* Pick the question whose responses drive the metric under **Question**.
* Under **Group by**, choose how to break the responses down. It defaults to **Choice** (group by answer option); **Month**, **Quarter**, and **Year** group by response date instead.
* Under **Calculation**, choose how responses roll up into the value. It defaults to **Response count**; **Percentage(%) of total** shows each group's share instead.

<figure><img src="/files/M7AYTLPaqeXi6J8WeHl6" alt="Add metric form with Source Qualtrics and Type Series selected. The Qualtrics field mapping is revealed below Type: Survey (enabled), Question (greyed out), Group by (greyed out), and Calculation."><figcaption><p>Qualtrics fields appear once a type is selected</p></figcaption></figure>

For what each field maps to in Qualtrics and the full option lists, see [Field mapping](#field-mapping) below.
{% endstep %}

{% step %}
**Pick the chart options**

In the **Default card preview** panel on the right, click **Show Preview** to render the chart from live data, then pick a default chart type from the chip strip (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Table**). Add an optional **Chart heading** and **Chart subheading** if you want labels above the chart.

<figure><img src="/files/LlcD279iiD8MNyHGYrGU" alt="Completed Qualtrics metric. The left column shows Survey, Question, Group by Choice, and Calculation Response count filled in. The right column shows a rendered bar chart preview with the chart-type strip (Bar chart selected) and Chart heading and Chart subheading inputs below."><figcaption><p>Completed configuration with a live preview</p></figcaption></figure>

These settings are the defaults for new cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md).
{% endstep %}

{% step %}
**Save the metric**

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.

<figure><img src="/files/OUVHL9KLRwYBUTcyqeM7" alt="Workspace Metrics tab with a populated list showing one metric. Columns are NAME, SOURCE, TYPE, CREATED, UPDATED, USED IN, and TAGS. Search, filter, and + Create metric controls sit above the table."><figcaption><p>Workspace Metrics tab with a saved metric</p></figcaption></figure>

For placing the metric as a card and customising it per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards.md).
{% endstep %}
{% endstepper %}

{% hint style="info" icon="tag" %}
On the **Free** plan, metric cards are capped at three per journey map. The **Framework** plan and above lift the cap.
{% endhint %}

***

#### Field mapping

Each Qualtrics field in the **Add metric** form points at a specific object in your survey. The selectors enable in order, so work down the form: **Question** unlocks once you pick a **Survey**, and **Group by** fills in once you pick a **Question**.

* **Survey** - The Qualtrics survey to pull responses from. Smaply lists only surveys the connected Qualtrics account can access. If the list is empty, that account hasn't been given access to any surveys in Qualtrics.
* **Question** - The survey question whose responses drive the metric. The list shows every question in the chosen survey.
* **Group by** - How responses are broken down on the chart. **Choice** groups by answer option (one bar or slice per answer). **Month**, **Quarter**, and **Year** group by when the response came in, which is useful for plotting a trend over time. Defaults to **Choice**.
* **Calculation** - How responses in each group roll up into a value. **Response count** plots the raw number of responses. **Percentage(%) of total** plots each group's share of all responses. Defaults to **Response count**.

For example, to chart how a satisfaction question breaks down by answer, pick the survey, pick the question, leave **Group by** on **Choice**, and leave **Calculation** on **Response count**. The chart then shows one bar per answer option, each bar the number of people who chose it.

<figure><img src="/files/vZhReRDNEw2fVUbFM1Uf" alt="Group by dropdown open on the Add metric form, listing Choice, Month, Quarter, and Year."><figcaption><p>Group by options</p></figcaption></figure>

<figure><img src="/files/jZbrWtEe6GEU2gwqwORY" alt="Calculation dropdown open on the Add metric form, listing Response count and Percentage(%) of total."><figcaption><p>Calculation options</p></figcaption></figure>

Once a survey is selected, the form also shows **Filters (items to include)** and **Filters (items to exclude)**, where you can narrow which responses feed the metric using AND and NOT conditions. These are optional. For the full filter reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md).

***

#### Refresh behaviour

Qualtrics metrics refresh on a rough hourly cycle. When you open the **Metrics** section or a journey map that contains a Qualtrics metric, Smaply pulls fresh responses if the last update was more than about an hour ago. There's no manual refresh button and no continuous or streaming pull, so newly submitted responses can take up to an hour to appear.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the question to the journey moment**

Pick the question that maps to the stage you want the metric to sit on. A post-purchase satisfaction question reads differently on an "Onboarding" stage than on a "Renewal" stage, even when the underlying numbers are the same.
{% endhint %}

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Qualtrics integration](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration.md) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>The Survey dropdown is empty</strong> - Connection account lacks survey access</summary>

The Source shows Qualtrics is connected, but no surveys appear in the **Survey** dropdown.

The Qualtrics account behind the connection doesn't have access to any surveys. Share the surveys you want to surface with that account in Qualtrics, then reopen the metric. If you connected with a dedicated account, confirm the expected surveys have been shared with it.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Mapping points at the wrong object</summary>

The metric saves and shows on a journey map, but the values are blank, wrong, or surprising.

Open the metric and check that **Survey**, **Question**, and **Calculation** still point at the objects you meant. It's easy to land on the wrong question, or to leave **Calculation** on **Response count** when you wanted **Percentage(%) of total**.

</details>

<details>

<summary><strong>A metric that worked before has stopped pulling</strong> - Question ID changed in Qualtrics</summary>

A metric that previously returned data starts coming back empty or broken.

Editing a question's text in place is fine, but deleting a question and re-adding it in Qualtrics gives it a new underlying ID, which breaks the metric's link to it. Edit the metric, re-pick the question under **Question**, and save.

</details>

<details>

<summary><strong>New responses aren't showing yet</strong> - Refresh window or no new responses</summary>

The survey has responses in Qualtrics, but the metric looks unchanged.

* The survey may have had no new responses since the last refresh, so the value is genuinely unchanged.
* Metrics refresh on load when the previous update is older than about an hour, so responses submitted in the last hour can take that long to appear. Reopen the map after the window passes.

</details>

If the values still look wrong after checking the mapping, you can send the raw response data to support for diagnosis. In **Account Settings > Integrations > Qualtrics**, the **Debug Configuration** section lets you select the affected survey and click **Download survey data** to export it. This lives on the account-level Qualtrics page, not in the metric builder. Send the file to <code class="expression">space.vars.supportEmail</code>.

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Set up Qualtrics</strong></td><td>Connect Qualtrics at the account level using an API token and base URL.</td><td><a href="/pages/qSgT2h9D9cKZgrZCWRx3">/pages/qSgT2h9D9cKZgrZCWRx3</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/integrations/metrics-tools/qualtrics/how-to-use-qualtrics-in-a-metric.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.