Cursor Integration

Customer Onboarding Guide — Cursor Organization Admin API (usage:* scope)

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.

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.

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

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.

1

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.

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.

2

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.

3

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.

4

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:

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

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)

• API Overview (auth, key creation)

• Cursor Pricing

OneLens Support: [e-mail]