Skip to main content
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.
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.

​
Setup

1

Open your Clarity project

Sign in to Clarity and open the project you want agents to read.
2

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.
3

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.
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.

​
Connection details

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

​
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.
Follow least privilege: generate a token used only by CloudThinker, so you can revoke it without affecting any other tool.

​
Agent capabilities

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

​
Verify the connection

​
Example prompts

​
Troubleshooting

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.
Clarity did not answer in time. Try connecting again.
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.
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.

​
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.

PostHog Connection

Product analytics, error triage, and flag changes

Alex Agent

Cloud and observability investigation agent