> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/ai/cursor.md).

# Cursor

Discover team members, track per-user usage, and manage members' spend limits across your Cursor workspace

Cursor is an AI-powered code editor built for developer productivity. Connecting Cursor to Harmony via the Team Admin API gives IT teams visibility into usage activity and AI request volume across the organization - making it easy to measure adoption and understand how the tool is being used.

#### What the Cursor integration enables

| Capability             | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| User Discovery         | Surface Cursor team members in Harmony's software inventory, derived from the last 7 days of usage data |
| Usage Tracking         | Monitor per-user activity, request volume, and the most-used AI model                                   |
| AI Request Metrics     | Track agent, chat, composer, and usage-based requests per user per day                                  |
| Spend Limit Management | Read and change members' spend limits from Custom Agents (Cursor Enterprise only)                       |
| Multi-Instance Support | Connect multiple Cursor workspaces for organizations with separate teams                                |

#### Prerequisites

* **Cursor Enterprise team**: Cursor lists the Team Admin API as available to Enterprise teams. A key without that entitlement returns `403 Forbidden` with the message `Enterprise access required`, and no Cursor data is synced
* **Cursor Team Admin**: Admin access to the Cursor team workspace, to create the API key
* **Team API Key**: A key starting with `crsr_` (see below)
* **Harmony Account**: Active Harmony workspace

#### Connect Cursor to Harmony

**Step 1: Generate a Team API Key**

1. Go to **cursor.com/dashboard** and open **API Keys**
2. Click **New API Key**
3. Give the key a descriptive name (e.g. `Harmony Integration`)
4. Copy the generated key - it starts with `crsr_`

{% hint style="warning" %}
Cursor shows the generated key only once. Copy it before closing the dialog - if you lose it, you will need to generate a new key.
{% endhint %}

**Step 2: Navigate to Integrations**

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Cursor** under **AI** (or search for it by name) and click its card

**Step 3: Enter Credentials**

1. If a Cursor instance is already connected, click **+ Create instance**
2. Enter an **Instance name** (required)
3. Paste your key in **Team API key**
4. Click **Connect**

{% hint style="info" %}
For organizations with multiple Cursor workspaces, you can add multiple instances by repeating this process for each workspace.
{% endhint %}

#### Disconnect Cursor from Harmony

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Cursor** under **AI** and click its card
4. Click the delete (trash) icon next to the instance you want to remove
5. Confirm when prompted

Once disconnected, Harmony stops syncing data from Cursor. Previously synced data remains available in Harmony. You can also revoke the key in Cursor at **cursor.com/dashboard** > **API Keys**.

#### Manage spend limits in agents

A Cursor team member can have their own spend limit; without one, the team's or their directory group's limit applies. Three Cursor steps in the Custom Agent Builder let an agent read and change these limits, for example to raise someone's limit after their manager approves it.

| Step                        | What it does                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Get User Spend Limit**    | Reads a member's own limit, the limit Cursor enforces for them, and what they have spent so far this billing cycle |
| **Set User Spend Limit**    | Sets a member's own spend limit, replacing any they already have                                                   |
| **Remove User Spend Limit** | Removes a member's own limit, so the team or group limit applies again. Does nothing when they have none           |

Pick the member as a Harmony employee (matched by their work email) or by email. Amounts are in dollars - enter `250` for $250. Cursor only accepts whole dollars, so a limit with cents is rounded up to the next dollar, never down.

Spend limit management is optional. Reading a member's limit works with the key you already connected; setting or removing one needs a Team API key with the `admin:*` scope. If your key has a narrower scope, create a new key with `admin:*` in **cursor.com/dashboard** > **API Keys**. Harmony does not let you change the key of an existing connection, so add the new key as a new Cursor instance (**+ Create instance**), pick it in your agents' settings, then delete the old instance with its trash icon. Only these three steps change anything in Cursor.

The [AI Usage Limits](https://github.com/harmonyso/public-docs/tree/main/ai-agents/agents/ai-usage-limits.md) agent uses these steps to raise a member's limit after approval.

{% hint style="warning" %}
Setting and removing a member's limit is available to **Cursor Enterprise** teams only, with a key that has the `admin:*` scope. Otherwise the steps stop with an error that says what is missing.
{% endhint %}

#### What Harmony Syncs

**From Cursor:**

* Team members (email address and activity status) - derived from daily usage data and deduplicated to reflect the most recent activity
* Each member's Cursor role label (for example `member`, `owner`, or `free-owner`), when the team members lookup is available on your plan. If it isn't, users still sync and their role is reported as not collected
* Per-user usage and activity data, including the most-used AI model, client version, line and tab counters
* Daily request volume broken down by type:
  * **Agent requests** - requests made through Cursor's agent mode
  * **Chat requests** - requests made through chat
  * **Composer requests** - requests made through Composer
  * **Usage-based requests** - requests recorded outside the subscription allowance

{% hint style="info" %}
Cursor's usage API does not expose seat type or billing status, so Harmony does not sync seat allocation, seat type (such as Premium, Super, Ultra or Free, or Standard on older Teams plans), or spend data. Spend is read only when an agent's **Get User Spend Limit** step asks for one member's. Display names are not synced either - Cursor user records in Harmony are identified by email address.
{% endhint %}

{% hint style="info" %}
**Sync cadence:**

* Usage data is pulled once every 24 hours
* The user inventory is refreshed every 6 hours, built from the last 7 days of usage data - a team member with no Cursor activity in that window does not appear in the inventory
  {% endhint %}

#### Permissions Explained

Harmony authenticates with a single Cursor **Team API key**. The sync only reads; the spend limit steps are the only thing that changes Cursor, and only when an agent runs them.

| What Harmony calls             | Why                                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /teams/daily-usage-data` | Per-user, per-day activity and request metrics - the source of both usage data and the user inventory                                            |
| `GET /teams/members`           | Reads each member's Cursor role label. Optional - if this call fails, roles are reported as not collected and the rest of the sync is unaffected |
| `POST /teams/spend`            | Reads one member's spend limits and spend this billing cycle, when an agent's spend limit step runs                                              |
| `POST /teams/user-spend-limit` | Sets or removes one member's own spend limit, when an agent's **Set** or **Remove User Spend Limit** step runs (Enterprise only)                 |

Things to know about the key:

* Team Admin API keys carry the `admin:*` scope, which is team-wide - the key is not scoped to an individual user
* The key is tied to your organization and is viewable by all team admins
* The key is unaffected by the original creator's account status, so it keeps working if that admin leaves the team
* Harmony does not create, modify, or remove Cursor members, seats, or settings. The one thing it can change is a member's own spend limit, and only through an agent's spend limit step

#### Use Cases

<details>

<summary>AI Tool Adoption</summary>

Track Cursor adoption across engineering teams to measure the impact of AI-assisted development. Use per-user request volume and model preferences to understand how deeply the tool is being used.

</details>

<details>

<summary>Usage Concentration</summary>

See which developers are actively using Cursor and how much, so you can compare active usage against what you're paying for. Note that the Harmony roster is built from the last 7 days of usage data - a developer with no recent Cursor activity is absent from the roster rather than listed as inactive.

</details>

<details>

<summary>Usage-Based Request Visibility</summary>

Monitor usage-based request volume per user to spot teams consuming beyond the subscription allowance. These are request counts as reported by Cursor, not billable amounts or spend - Harmony does not sync Cursor billing data.

</details>

<details>

<summary>Spend Limit Increases</summary>

Let developers ask for more Cursor usage, route the request for approval, and raise their limit automatically - or reset temporary increases when the billing cycle starts again

</details>

<details>

<summary>Offboarding</summary>

Confirm Cursor access has been removed when developers leave, as part of Harmony offboarding agents

</details>

#### Troubleshooting

<details>

<summary>No Cursor data appears after connecting</summary>

**Possible causes:**

* The Cursor team does not have Team Admin API access. Cursor lists this API as available to Enterprise teams, and other plans receive `403 Forbidden` with the message `Enterprise access required`
* The first sync has not completed yet
* Nobody on the team has used Cursor in the last 7 days, so there is nothing to derive an inventory from

**Solutions:**

1. Confirm your Cursor plan includes Team Admin API access
2. Allow up to 24 hours for the first full usage sync - the user inventory refreshes every 6 hours
3. Verify in Cursor that the team has recent activity

</details>

<details>

<summary>Users appear but their role is missing</summary>

**Possible causes:**

* The `GET /teams/members` lookup did not succeed - for example, the endpoint is not available on your plan, or the call was rate limited

**Solutions:**

1. This does not break the integration - users are still synced from usage data, and Harmony reports the role as not collected rather than guessing it
2. Confirm the key has the `admin:*` scope and that your plan includes Team Admin API access

</details>

<details>

<summary>Sync appears slow or incomplete on large teams</summary>

**Possible causes:**

* Cursor rate limits the Admin API to 20 requests per minute per team, and returns `429 Too Many Requests` when exceeded

**Solutions:**

1. Harmony paces its requests to stay within this limit and retries after a rate limit response, so large teams simply take longer to sync
2. If you have other tools using the same team API key, they share the same per-team limit

</details>

<details>

<summary>Rotating the API key</summary>

Cursor keys are generated in **cursor.com/dashboard** > **API Keys**. To rotate, generate a new key and add it in Harmony as a new Cursor instance (**+ Create instance**). Switch anything that uses the old instance to the new one, delete the old instance with its trash icon, and then revoke the old key in Cursor.

</details>

#### Data & Privacy

<details>

<summary>Key privacy principles</summary>

For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).

* Harmony's sync reads Cursor data and does not modify your Cursor account. Members' spend limits change only when an agent you built runs a Set or Remove User Spend Limit step
* The integration can be revoked at any time by disconnecting it in Harmony or revoking the API key in Cursor

</details>

<details>

<summary>Developer productivity data</summary>

The Cursor usage API returns per-developer daily productivity counters, and Harmony ingests them alongside request volume:

* Lines added and accepted lines added
* Tab completions shown and accepted
* Most-used AI model and most-used file extension
* Cursor client version

Harmony does not receive code content, prompts, or conversation contents - only these aggregate daily counters. In some jurisdictions per-developer productivity metrics are subject to works council or employee monitoring requirements, so review this with your legal or privacy team before enabling the integration.

</details>


---

# 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.harmony.io/integrations/ai/cursor.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.
