> For the complete documentation index, see [llms.txt](https://docs.onelens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelens.cloud/integrations/ai-integrations/cursor-integration.md).
# Cursor Integration
## TL;DR
**What this does:** Connects OneLens to your Cursor organization to pull per-team and per-user usage and spend data — giving you unified cost visibility, anomaly detection, and optimization insights across your Cursor seats and model usage (input/output/cache tokens, included vs. usage-based requests, per-model activity).
**Time required:** \~5 minutes
**Who you need:** A Cursor organization **Admin** (to create a scoped Organization API key).
**What OneLens reads:** Read-only usage and spend metadata from the Cursor Organization Admin API, using a key scoped to **`usage:*`** (not `admin:*`). Your code, prompts, chats, and completions are never accessed.
{% hint style="warning" %}
**Scope matters.** OneLens needs only the `usage:*` scope — read-only access to pooled usage and reporting endpoints. A `usage:*` key **cannot** manage members, change settings, or perform any administrative writes. Do **not** issue a full `admin:*` key for this integration.
{% endhint %}
## What You'll Get Once Connected
| Capability | What it does for you |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Per-Team & Per-User Cost Attribution** | See exactly what each team and member in your Cursor org spends. |
| **Pooled Usage Tracking** | Track pooled spend limits and per-team consumption against your contract window. |
| **Token-Level Cost Breakdown** | Break spend down by input, output, cache-write, and cache-read tokens per event. |
| **Usage-Based vs. Included Requests** | Separate subscription-included requests from usage-based (overage) requests. |
| **Per-Model Usage Breakdown** | See model usage and how model choice affects cost, including Cursor Token Rate on third-party models. |
| **Developer Activity Metrics** | Track lines added/accepted, applies, accepts/rejects, chat/composer/agent requests per user, per day. |
| **Cost Anomaly Detection** | Get alerted when Cursor spend deviates from historical patterns — catch spikes early. |
| **Budget Tracking** | Set and monitor budgets at the org, team, or user level with OneLens alerts. |
| **Multi-Provider Visibility** | View Cursor costs alongside OpenAI, Anthropic, AWS Bedrock, LiteLLM, and other providers in one dashboard. |
## Security at a Glance
| Question | Answer |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Does OneLens read our code, prompts, or chats?** | No. The reporting endpoints return only aggregated spend, token counts, request counts, activity metrics, and model identifiers. No source code, prompt, or chat content is included. |
| **What scope does the key need?** | Only **`usage:*`** — read-only access to pooled usage and reporting endpoints. Not `admin:*`. |
| **Can the key modify our org?** | No. A `usage:*` key cannot manage members, groups, settings, or spend limits — it performs no administrative writes. |
| **Is the access read-only?** | Yes. OneLens calls only the four usage/spend reporting endpoints below. |
| **What authentication is used?** | A Cursor **Organization API key** scoped to `usage:*`, created by an org Admin. Passed via HTTP Basic Auth (key as the username, empty password). |
| **Does OneLens see user identifiers?** | Yes — the API returns `userId`, `email`, and `teamId` values used for per-user and per-team cost attribution. |
| **How is data transmitted and stored?** | All API calls use HTTPS/TLS 1.2+. Credentials are encrypted at rest using GCP KMS in OneLens infrastructure. |
## Cost of the Integration
OneLens reads usage and spend metadata via the Cursor Organization Admin API. There is no additional charge from Cursor for API queries.
| Item | What it is | Typical cost |
| ----------------------- | ----------------------------------------------------------- | -------------------------------- |
| API calls | Hourly polling of the usage/spend endpoints with pagination | $0 (no per-request charge) |
| Data egress | JSON metadata responses | $0 |
| Compute in your account | None — OneLens calls Cursor's hosted API | $0 |
| **Estimated total** | | **$0/month on your Cursor bill** |
## How It Works
The Cursor Organization Admin API provides programmatic access to usage and spend data across your Cursor organization. With a `usage:*`-scoped key, OneLens calls four endpoints:
* **`POST /organizations/pooled-usage`** — pool-level spend limits and per-team usage against the contract window.
* **`POST /organizations/filtered-usage-events`** — granular per-event token usage and cost (`inputTokens`, `outputTokens`, `cacheWriteTokens`, `cacheReadTokens`, `chargedCents`, `cursorTokenFee`).
* **`POST /organizations/daily-usage-data`** — per-user, per-day activity and request metrics.
* **`POST /organizations/spend`** — per-member spend over the organization contract window.
Every request carries your `organizationId`, which must match the key's organization. OneLens polls once per hour (Cursor rate-limits usage endpoints to hourly polling, 20 req/min), iterating over the configured date range and handling pagination automatically. All monetary fields are reported in cents and normalized into a unified cost model alongside your other AI providers.
## Prerequisites
* A Cursor **organization** on an **Enterprise** plan (the Organization Admin API is Enterprise-only)
* A user with the **Admin** role on the organization
* Access to the Cursor dashboard (`cursor.com/dashboard`)
* Your Cursor **Organization ID** (starts with `org_`)
## What OneLens Will Access
| Endpoint | Purpose |
| ------------------------------------------- | -------------------------------------------- |
| `POST /organizations/pooled-usage` | Pool spend limits + per-team usage breakdown |
| `POST /organizations/filtered-usage-events` | Granular per-event token usage and cost |
| `POST /organizations/daily-usage-data` | Per-user, per-day usage and activity metrics |
| `POST /organizations/spend` | Per-member spend over the contract window |
**Parameters used:**
| Parameter | Value | Purpose |
| ---------------- | ------------------ | ----------------------------------------------------- |
| `organizationId` | `org_...` | Must match the API key's organization |
| `startDate` | epoch milliseconds | Start of the query window |
| `endDate` | epoch milliseconds | End of the query window (daily-usage range ≤ 30 days) |
| `page` | page number | Pagination |
| `pageSize` | page size | Pagination page size |
### What OneLens Will NOT Access
* Any code, files, or repository content in your Cursor workspace
* Any prompt, chat, composer, or completion content
* Model invocation — OneLens cannot run Cursor Agent, Chat, or any model
* Member/group management — the `usage:*` scope grants no `members:*` or `admin:*` write access
* Organization settings or spend-limit configuration
* Billing or payment method details
{% hint style="info" %}
**Note:** The `usage:*` scope is strictly read-only over the four reporting endpoints above. The key OneLens uses cannot invoke models or modify any organization resource.
{% endhint %}
{% stepper %}
{% step %}
## Create a Scoped Organization API Key
1. Sign in to the Cursor dashboard (`cursor.com/dashboard`) as an organization **Admin**.
2. Navigate to **API Keys**.
3. Click **Create API Key**.
4. Name it **OneLens Integration** (use a dedicated key so it can be rotated or revoked independently).
5. Set the scope to **`usage:*`** — **not** `admin:*`.
6. Copy the key — you'll paste it directly into the OneLens integration form. No need to share it over email or chat.
{% hint style="warning" %}
**Important:** Only org Admins can create Organization API keys. A `usage:*` key reads usage and spend only — it cannot invoke models, read code, or perform administrative writes.
{% endhint %}
{% endstep %}
{% step %}
## Find Your Organization ID
1. In the Cursor dashboard, open your organization settings.
2. Copy your **Organization ID** (starts with `org_`). It must match the key's organization.
{% endstep %}
{% step %}
## Connect to OneLens
In OneLens, open the **Integrations** page, select the **Cursor** integration, and enter the following directly in the setup form (the key is encrypted at rest — no external key-sharing step required):
| Field | Value | Example |
| ---------------- | ------------------------------------------ | ------------------ |
| Integration Name | A display name for this connection | `Acme Corp Cursor` |
| Organization ID | Your Cursor organization ID | `org_xxxxxxxxxxxx` |
| API Key | Your `usage:*`-scoped Organization API key | `key_xxxx...xxxx` |
OneLens will begin ingesting data on the next scheduled poll.
{% endstep %}
{% step %}
## Verify the Connection
After connecting, verify by checking the OneLens dashboard for:
* Cursor spend appearing in the cost explorer
* Per-team and per-user cost data populating
* Historical usage data backfilling (up to the available date range)
If data doesn't appear within 24 hours, run this from your terminal to confirm the key and scope work independently:
```bash
curl -X POST "https://api.cursor.com/organizations/spend" \
-u YOUR_CURSOR_USAGE_KEY_HERE: \
-H "Content-Type: application/json" \
-d '{"organizationId": "org_xxxxxxxxxxxx", "sortBy": "spendCents", "sortDirection": "desc", "page": 1, "pageSize": 10}'
```
(Note the trailing `:` after the key — Basic Auth uses the key as the username with an empty password.)
{% endstep %}
{% endstepper %}
## Data Refresh Schedule
* OneLens polls the usage/spend endpoints once in 24 hours (Cursor rate-limits usage endpoints to once per hour).
* Spend figures reconcile to your organization contract window.
* Current-cycle figures may shift as usage accrues through the billing period.
* Historical data is backfilled automatically on initial connection.
## Data Privacy & Security
* **Least-privilege scope** — OneLens uses a `usage:*` key, read-only over the four reporting endpoints; no `admin:*` write access.
* **No code or prompt content** — the reporting endpoints return only aggregated spend, token counts, request counts, activity metrics, and model names.
* **TLS in transit** — all API calls use HTTPS/TLS 1.2+.
* **Encrypted at rest** — the key is entered directly in the OneLens integration form and encrypted at rest using GCP KMS; no external key-sharing tool is involved.
* **Dedicated & rotatable** — use a dedicated key for this integration so it can be rotated or revoked independently.
* **Data retention** — 12-month default, configurable. Deletion within 30 days on request with confirmation.
## Frequently Asked Questions
Do we need to give OneLens a full admin key?
No. Issue a key scoped to `usage:*` only. It grants read-only access to pooled usage and reporting endpoints and cannot manage members, change settings, or perform any administrative writes.
Can OneLens see our code, prompts, or chats?
No. The reporting endpoints expose only usage and spend metadata — token counts, request counts, cost amounts, activity metrics, and model identifiers. No source code, prompt, or chat content is ever returned.
Can OneLens invoke models or run up our Cursor bill?
No. The Organization Admin API cannot invoke Cursor Agent, Chat, or any model. It is read-only for reporting data.
Will this impact our developer experience or rate limits?
No. OneLens polls the usage endpoints in the background at most once per hour and stays within Cursor's 20 req/min limit. It does not touch the endpoints your developers use.
Is this available on all Cursor plans?
No. The Organization Admin API is **Enterprise-only**.
Can I connect multiple Cursor organizations?
Yes. Create one `usage:*` key per organization and add each as a separate OneLens integration.
How do I disconnect OneLens?
Remove the integration in OneLens, then revoke the Organization API key in the Cursor dashboard.
How do I rotate the API key?
Create a new `usage:*` key in the Cursor dashboard, update it in the OneLens integration setup, then revoke the old key.
Does OneLens see user email addresses?
Yes — the API returns `email` (and `userId`, `teamId`) for per-user and per-team cost attribution. These are used only to label spend and usage in the dashboard.
## Need Help?
**Cursor Documentation:**
* [Organization Admin API (scopes + usage endpoints)](https://cursor.com/docs/account/organizations/organization-admin-api)
* [API Overview (auth, key creation)](https://cursor.com/docs/api)
* [Cursor Pricing](https://cursor.com/pricing)
**OneLens Support:**
---
# 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://docs.onelens.cloud/integrations/ai-integrations/cursor-integration.md?ask=&goal=
```
`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.