> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Clarity

> Connect Microsoft Clarity to CloudThinker to query traffic and engagement metrics and find matching session recordings

Connect your Microsoft Clarity project to let CloudThinker agents answer questions about traffic, engagement, and scroll depth, and find session recordings that match a filter. Clarity authenticates with a **Data Export API token** that belongs to one project, and the connection is read-only.

## Prerequisites

* A **Microsoft Clarity project** that is already collecting data.
* A **project admin** role. Microsoft states that only project admins can manage access tokens.

<Info>
  Clarity's Data Export API allows a maximum of 10 API requests per project per day and returns only the previous 1 to 3 days. One token covers one project, so a second project needs its own token and connection.
</Info>

## Setup

<Steps>
  <Step title="Open your Clarity project">
    Sign in to Clarity and open the project you want agents to read.
  </Step>

  <Step title="Generate an API token">
    Go to **Settings → Data Export** and click **Generate new API token**. Give it a name of 4 to 32 characters, such as `cloudthinker`. Names can use letters, numbers, hyphens, underscores, and periods, with no spaces, and must be unique in the project. Copy the token and store it securely.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → Microsoft Clarity** and click **Connect**. Paste the token into the **CLARITY\_API\_TOKEN** field and click **Connect**. CloudThinker sets up the connection and shows a **Connected** status.
  </Step>
</Steps>

<Note>
  **Connected** means CloudThinker finished setting up the connection. Clarity checks the token the first time an agent calls it, so a wrong or revoked token can still show **Connected**. Run the verify prompt below to confirm.
</Note>

## Connection details

| Field | Description | Example |
| - | - | - |
| **CLARITY\_API\_TOKEN** | Data Export API token generated in your Clarity project | `<your-api-token>` |

<Note>
  Clarity returns results in UTC, so a day in an answer follows UTC, not your local time.
</Note>

## Required permissions

The token reads the data of the project that generated it and nothing else. Microsoft documents no per-token scopes, so your controls are who generates the token and which project it belongs to.

<Tip>
  Follow least privilege: generate a token used only by CloudThinker, so you can revoke it without affecting any other tool.
</Tip>

## Agent capabilities

Once connected, agents have read access to your project's data.

| Capability | Description |
| - | - |
| **Traffic and engagement** | Report sessions, engagement time, and scroll depth |
| **Segments** | Break results down by browser, device, operating system, country or region, and traffic source |
| **Behavior signals** | Report dead clicks, rage clicks, and script errors |
| **Session recordings** | List recordings filtered by time, device, browser, operating system, or country, up to 250 per request |

### Verify the connection

```text theme={null}
Show Microsoft Clarity traffic for the last day, broken down by device
```

### Example prompts

```text theme={null}
Compare scroll depth on mobile and desktop over the last 3 days in Clarity
Which countries had the most rage clicks in Clarity yesterday
List recent Clarity session recordings from mobile devices
```

## Troubleshooting

<Accordion title="Connected, but every request fails with 401">
  Clarity refused the token. It may be revoked, mistyped, or generated for a different project. Generate a new token in the project you want and update the connection.
</Accordion>

<Accordion title="This connection did not respond in time. Try connecting again.">
  Clarity did not answer in time. Try connecting again.
</Accordion>

<Accordion title="Agents report a daily limit or return no data">
  Clarity's Data Export API returns a Too Many Requests error once a project passes 10 requests in a day, and it only covers the previous 1 to 3 days. Wait for the next day. A broad overview question can use several of the day's requests, so ask one focused question at a time.
</Accordion>

<Accordion title="A result looks incomplete">
  A single response holds at most 1,000 rows and cannot be paged, and a request can break results down by at most three dimensions. Narrow the question to one metric and fewer segments.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Replace tokens when access changes** — Microsoft advises promptly replacing API tokens if a user with access is removed from the project.
- **Treat the token like a password** — it can read your project's analytics, so keep it out of chat and code.

## Related

<CardGroup cols={2}>
  <Card title="PostHog Connection" icon="https://mintcdn.com/cloudthinker/fJM2cOggET3WD6Z_/images/icons/posthog.svg?fit=max&auto=format&n=fJM2cOggET3WD6Z_&q=85&s=49f47c2129f89c159e36a9c242e7d28a" href="/guide/connections/posthog" width="50" height="30" data-path="images/icons/posthog.svg">
    Product analytics, error triage, and flag changes
  </Card>

  <Card title="Alex Agent" icon="cloud" href="/guide/agents/alex">
    Cloud and observability investigation agent
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.