> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/developer-reference/export-heart-nps-survey-tag-and-task-data-via-api.md).

# Export HEART, NPS, Survey, Tag, and Task data via API

Export HEART, NPS, Survey, Tag, and Task data through the REST API.

## About the analytics APIs

The analytics APIs export HEART Scores, NPS responses, Survey responses, Tag interaction data, and Task adoption data from a Userlane property in JSON format.

## Why use it

Use the data to:

* track the HEART Score over time
* pull NPS and Survey responses into reporting alongside other feedback channels
* measure feature adoption with Tag data
* combine Userlane analytics with locally held user data, such as role, region, or department
* measure Task completion and drop-off

## What can be exported

There are five analytics APIs. Choose based on the question to be answered.

| Question                                                    | API                                                                                     |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| What is the current HEART Score?                            | [HEART API](https://dev.userlane.com/reference/heartdata-1)                             |
| Who are the promoters and detractors?                       | [NPS API](https://dev.userlane.com/reference/etting-started-with-nps-responses)         |
| How satisfied are users with a specific feature or flow?    | [Surveys API](https://dev.userlane.com/reference/getting-started-with-survey-responses) |
| Which features are users actually clicking?                 | [Tags API](https://dev.userlane.com/reference/getting-started-with-tags)                |
| Are users completing key Tasks, and where do they drop off? | [Tasks API](https://dev.userlane.com/reference/getting-started-with-the-tasks-api)      |

All five APIs return JSON.

### HEART API

Returns daily HEART Scores for an application: the overall composite score plus the score for each of the five dimensions, Happiness, Efficiency, Adoption, Risk, and Task success, along with user and session counts. For what each dimension measures and how it is weighted, see [HEART](/intelligence/heart.md).

Use it to track the score over time and identify which dimension is driving a change in the overall score.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FYRQVoY0EyMoV3Nw9Jhyh%2Fimage.png?alt=media\&token=0bce8e5c-30bb-4135-9f66-1c628a72d1fd)

### NPS API

Returns individual responses to Net Promoter Score surveys: score from 0 to 10, optional free-text comment, timestamp, and user ID. Responses fall into promoters at 9 to 10, passives at 7 to 8, and detractors at 0 to 6.

Use it to track sentiment trends, identify champions and at-risk users, and mine free-text comments for themes.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FAzZY2Gqi3YJbSR1qbg0A%2Fimage.png?alt=media\&token=b07f8869-c60b-4733-9070-8da9b5976faa)

### Surveys API

Returns individual responses to in-app Surveys: score from 1 to 5, optional free-text comment, timestamp, and user ID. Unlike NPS, which asks one fixed question across the product, a Survey can be scoped to a specific moment or feature.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FvcifoIZkt4vLhuDX7sM4%2Fimage.png?alt=media\&token=6fc357b0-9e70-46a9-841a-db185415e78b)

The request needs the Survey ID, which is available in the Portal.

### Tags API

Returns per-user, per-Tag, per-day interaction counts on tagged elements: the buttons, links, or pages marked in the Userlane Portal as meaningful actions.

Use it to measure feature adoption, identify power users, spot adoption gaps by audience, and track how usage of one feature changes over time.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FVnmA6AqgqFzR0JetWZ27%2Fimage.png?alt=media\&token=c9663724-4e44-42a5-bac9-91dc322e5b27)

### Tasks API

Returns Task adoption data through two endpoints. The aggregated endpoint gives per-user, per-day starts, completions, and time to complete across all Tasks in a property. The actions endpoint gives the raw, step-by-step event stream for one Task.

Use the aggregated endpoint to track completion rates and spot Tasks with high drop-off.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FaLTrPuV7IvdkLClrlS61%2Fimage.png?alt=media\&token=62dac3dd-27d0-4443-b3b4-e353b497b323)

Use the actions endpoint to see exactly which step within a Task users abandon.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FPw1gRDooFNIehRC70HwD%2Fimage.png?alt=media\&token=391e8645-63ac-4fdd-8185-33326d13f281)

API responses do not carry audience information. To analyze results by audience or by user attribute, join the export with the user profile data export on the user ID. See [User profile data export](/developer-reference/user-profile-data-export.md).

## Data retention

Each API returns a limited window of history. Requests reaching further back return no data, even where the date range is otherwise valid.

| Data                     | History available |
| ------------------------ | ----------------- |
| NPS responses            | Last 2 years      |
| Survey responses         | Last 2 years      |
| Tags                     | Last 2 years      |
| Tasks (actions endpoint) | Last 31 days      |

For longer history, schedule a regular pull into a local database.

## Resolving IDs to names

Tag, Survey, NPS, and Task responses return numeric IDs rather than names. Matching those IDs to their titles makes the export usable in a report or dashboard.

**Tags:** open the Tag analytics page in the Userlane Portal and export the list to CSV. The export includes both Tag ID and name.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FfUkO5nP5L479wqwdCmWc%2Fimage.png?alt=media\&token=e1e4f141-cbb0-4431-92d9-91c74bebe016)

**Surveys and NPS:** there is only one NPS, so no ID needs resolving. The Survey ID is a required request parameter and is visible in the URL of the corresponding Survey in the Userlane Portal.

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FZQ0vi6Smuds9yaHy8GWr%2Fimage.png?alt=media\&token=c87a5211-144d-4e2b-bdc7-c7fefac19c44)

**Tasks:** the aggregated endpoint returns a numeric `taskId`. Export the Task list from the Userlane Portal to get the Task ID and name. The actions endpoint also returns a numeric `actionId`. Open the Task page in the Portal and export its action chart, which lists each action ID and name, for example Open page, Enter input element, Click SAVE. Join on `actionId` to show readable step names.

Join the API export with the CSV lookup in the reporting tool to display names instead of numeric IDs.

## How to export the data

### Generate the token

The export is protected and requires an authorization token. Generate the token in the Userlane Portal under **Settings > API Token**. See [Your Userlane API token](/developer-reference/your-userlane-api-token.md).

![](https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2F7LojDrGBhKV7OOXdSEZW%2Fimage.png?alt=media\&token=130843f8-5b40-4126-82c1-f8ebecaf1768)

The token is generated per Userlane Manager and can be regenerated at any time using the same button in the Portal.

### Run the request

Each API is available in the developer documentation, which includes a Try it button for testing a request directly in the browser.

* [HEART API](https://dev.userlane.com/reference/heartdata-1)
* [NPS API](https://dev.userlane.com/reference/etting-started-with-nps-responses)
* [Surveys API](https://dev.userlane.com/reference/getting-started-with-survey-responses)
* [Tags API](https://dev.userlane.com/reference/getting-started-with-tags)
* [Tasks API](https://dev.userlane.com/reference/getting-started-with-the-tasks-api)

Each request needs:

* **Property ID:** the Userlane ID of the application. In the API, a property is what the Userlane Portal calls an application.
* **Survey ID:** required for Surveys only.
* **Start and end dates:** the time span for the export.
  * HEART, NPS, Surveys, and Tags use the format `2026-04-01T00:00:00+00:00`.
  * The Tasks API treats `start` and `end` as inclusive UTC calendar dates. The time of day is ignored, so the whole of the end day is always included. The Tasks actions endpoint additionally requires `start` to fall within the last 31 days.
  * HEART is smoothed over a rolling 90-day window. The Tasks API returns the actual events in the requested window, with no smoothing.
* **Pagination:** handled two ways depending on the API.
  * HEART, NPS, Surveys, and Tags use page-based pagination, with up to 1,000 records per page. Request each page by changing the page number.
  * The Tasks API uses cursor-based pagination. Leave the cursor empty on the first request, then pass the `nextCursor` value from each response back as the `cursor` parameter until it returns null. There is no page number for Tasks.
* **Authorization token:** pasted into the authentication field.

Once the request runs successfully, copy the JSON response, or the request code, using the copy icon.

## Rate limits

The API accepts up to 2 requests per minute. Exceeding that returns HTTP 429, and the next request has to wait.

One page returns up to 1,000 records, so an export spanning many pages has to be spaced out to stay inside the limit. Pulling once per day is the recommended pattern. More frequent pulls increase the chance of retrieving the same events twice.

## Troubleshooting

A failed request returns an error message in the result section. Most errors relate to:

* an incorrect date format
* an invalid or expired authorization token
* a 429 response, meaning the rate limit of 2 requests per minute was exceeded

Review the parameters against this article. If the issue persists, contact Userlane.

## Relevant articles

{% content-ref url="/pages/TBF4QYHDMWQghy26u8xI" %}
[HEART](/intelligence/heart.md)
{% endcontent-ref %}

{% content-ref url="/pages/TcXdqgybeGLnS1EODhcN" %}
[Your Userlane API token](/developer-reference/your-userlane-api-token.md)
{% endcontent-ref %}

{% content-ref url="/pages/YQr5VKi5bSxWYT6o6dOi" %}
[Export Guides, Guide progress, and Announcement data via API](/developer-reference/export-guides-guide-progress-and-announcement-data-via-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/0XiPZYLLfKewriq8G6Av" %}
[User profile data export](/developer-reference/user-profile-data-export.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/developer-reference/export-heart-nps-survey-tag-and-task-data-via-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.