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
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
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.
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
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:
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 nomembers:*oradmin:*write accessOrganization 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.
Create a Scoped Organization API Key
Sign in to the Cursor dashboard (
cursor.com/dashboard) as an organization Admin.Navigate to API Keys.
Click Create API Key.
Name it OneLens Integration (use a dedicated key so it can be rotated or revoked independently).
Set the scope to
usage:*— notadmin:*.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.
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):
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.
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:
(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; noadmin:*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.
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:
OneLens Support: support@astuto.ai
Last updated

