Cursor metrics
Port's Cursor integration allows you to ingest daily usage, usage events, model usage, and skill adoption analytics into your software catalog.
Prerequisites
- A Cursor API key with permissions to read organization or team usage metrics.
- A Cursor Teams or Cursor Enterprise plan. Please refer to the Cursor API availability docs to see what is available with Teams and Enterprise licenses.
- Your Port user role is set to
Admin.
Setup
Choose one of the installation methods below. If you are not sure which option to use, review the installation methods overview.
The prerequisites required for installation are listed below.
-
Go to the Cursor Connectors page in Port.
-
Under
Select your installation method, chooseHosted by Port. -
Configure the
Installation parametersandAdvanced configurationas you wish (see below for details).
Installation parameters
Each integration requires specific parameters (such as an API token, a URL, etc.), as seen in Port's UI when installing it. Hover over the ⓘ icon next to each parameter to see more details about it.
Advanced configuration
- During the installation process each integration may have additional settings under the
Advanced configurationsection in Port's UI. Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Connectors page and navigate to theSettingtab. Hover over the ⓘ icon next to each setting to see more details about it.
Port secrets
Some integration settings require sensitive pieces of data, such as tokens. For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.
When filling in such a setting, its value will be obscured (shown as ••••••••).
For each such setting, Port will automatically create a secret in your organization.
To see all secrets in your organization, follow these steps.
Port source IP addresses
When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:
- Europe (EU):
54.73.167.226,63.33.143.237,54.76.185.219 - United States (US):
3.234.37.33,54.225.172.136,3.225.234.99
-
Go to the Cursor Connectors page in your portal.
-
Select the
Self-hostedmethod. -
A
helmcommand will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.
Live event support
Currently, live events are not supported for this integration.
Resyncs will be performed periodically (with a configurable interval), or manually triggered by you via Port's UI.
Therefore, real-time events (including GitOps) will not be ingested into Port immediately.
Live events support for this integration is WIP and will be supported in the near future.
The resync interval can be configured using the scheduledResyncInterval parameter. See the optional parameters section below for more details.
port.clientId- Your Port client ID.port.clientSecret- Your Port client secret.port.baseUrl- Your Port API URL (https://api.port.iofor EU,https://api.us.port.iofor US).integration.identifier- A unique identifier for your integration.integration.type- The integration type to install.integration.eventListener.type- Event listener type. Read more about event listeners.integration.secrets.cursorApiKey- Cursor API key used to query team usage and analytics endpoints.
**Optional parameters (click to expand)**
integration.config.cursorApiHost- Cursor API host. Defaults tohttps://api.cursor.com.scheduledResyncInterval- Number of minutes between each resync. When not set, the integration resyncs for each event listener resync event.initializePortResources- Whentrue, the integration creates default blueprints and Port app config mapping.sendRawDataExamples- Whentrue, sends raw data examples to Port for testing and managing the integration mapping.
- GitHub
- Jenkins
- Azure DevOps
- GitLab
- Go to the Cursor Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitHub Actions secret |
|---|---|---|---|
port_client_id | Your Port client ID (How to get the credentials). | ✓ | ✓ |
port_client_secret | Your Port client secret (How to get the credentials). | ✓ | ✓ |
port_base_url | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
cursor_api_key | Cursor API key used to query usage and analytics endpoints. | ✓ | ✓ |
cursor_api_host | Cursor API host. Defaults to https://api.cursor.com. | ✗ | ✗ |
initialize_port_resources | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
integration_identifier | The identifier of the integration that will be installed. | ✗ | ✗ |
send_raw_data_examples | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Your Jenkins agent must be able to run Docker commands.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a Jenkins credential (Secret Text) |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | Cursor API key used to query usage and analytics endpoints. | ✓ | ✓ |
OCEAN__ | Cursor API host. Defaults to https://api.cursor.com. | ✗ | ✗ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a Jenkinsfile pipeline file:Jenkins pipeline (click to expand)
Prerequisites
- Your Azure Devops agent should be able to run docker commands. Learn more about agents here.
- You must have permissions to create and manage Azure DevOps variable groups for storing credentials.
Set up your credentials
- Create a Variable Group: Name it port-ocean-credentials.
- Store the required variables (see the table below).
- Authorize Your Pipeline:
-
Go to "Library" -> "Variable groups."
-
Find port-ocean-credentials and click on it.
-
Select "Pipeline Permissions" and add your pipeline to the authorized list.
-
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as an Azure DevOps pipeline variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | Cursor API key used to query usage and analytics endpoints. | ✓ | ✓ |
OCEAN__ | Cursor API host. Defaults to https://api.cursor.com. | ✗ | ✗ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a azure-pipeline.yml pipeline file:Azure pipeline (click to expand)
- Go to the Cursor Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitLab CI/CD variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | Cursor API key used to query usage and analytics endpoints. | ✓ | ✓ |
OCEAN__ | Cursor API host. Defaults to https://api.cursor.com. | ✗ | ✗ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Configuration
Port integrations use a YAML mapping block to ingest data from third-party APIs into Port.
The mapping uses the JQ JSON processor to transform fields and shape incoming Cursor data into Port entities.
Default mapping configuration
This is the default mapping configuration for this integration:
Default mapping configuration (click to expand)
resources:
- kind: cursor-daily-usage
selector:
query: 'true'
startDate: 30d
endDate: 0d
port:
entity:
mappings:
identifier: (.userId + "-" + .day)
title: (.email + " " + .day)
blueprint: '"cursorDailyUsage"'
properties:
day: (if .day then (.day + "T00:00:00Z") else null end)
user_id: .userId
email: .email
is_active: .isActive
total_lines_added: .totalLinesAdded
total_lines_deleted: .totalLinesDeleted
accepted_lines_added: .acceptedLinesAdded
accepted_lines_deleted: .acceptedLinesDeleted
total_applies: .totalApplies
total_accepts: .totalAccepts
total_rejects: .totalRejects
total_tabs_shown: .totalTabsShown
total_tabs_accepted: .totalTabsAccepted
composer_requests: .composerRequests
chat_requests: .chatRequests
agent_requests: .agentRequests
most_used_model: .mostUsedModel
subscription_included_reqs: .subscriptionIncludedReqs
api_key_reqs: .apiKeyReqs
usage_based_reqs: .usageBasedReqs
bugbot_usages: .bugbotUsages
- kind: cursor-usage-event
selector:
query: 'true'
startDate: 30d
endDate: 0d
port:
entity:
mappings:
identifier: ((.timestamp + "-" + .userEmail + "-" + .model + "-" + .kind) | gsub("[^A-Za-z0-9@_.+:\\\\/='-]"; "_"))
title: (.userEmail + " " + .model + " " + .kind)
blueprint: '"cursorUsageEvent"'
properties:
timestamp: (.timestamp | tonumber / 1000 | todate)
model: .model
kind: .kind
max_mode: .maxMode
requests_costs: .requestsCosts
is_token_based_call: .isTokenBasedCall
token_usage: .tokenUsage
user_email: .userEmail
cursor_token_fee: .cursorTokenFee
is_headless: .isHeadless
charged_amount: (if .chargedCents then (.chargedCents / 100) else null end)
- kind: cursor-team-model-usage
selector:
query: 'true'
startDate: 30d
endDate: 0d
port:
itemsToParse: (.model_breakdown // {} | to_entries)
entity:
mappings:
identifier: (.date + "-" + .item.key)
title: (.date + " " + .item.key)
blueprint: '"cursorTeamModelUsage"'
properties:
date: (if .date then (.date + "T00:00:00Z") else null end)
model: .item.key
messages: .item.value.messages
users: .item.value.users
- kind: cursor-user-model-usage
selector:
query: 'true'
startDate: 30d
endDate: 0d
port:
itemsToParse: (.model_breakdown // {} | to_entries)
entity:
mappings:
identifier: (.userEmail + "-" + .date + "-" + .item.key)
title: (.userEmail + " " + .item.key)
blueprint: '"cursorUserModelUsage"'
properties:
date: (if .date then (.date + "T00:00:00Z") else null end)
user_email: .userEmail
model: .item.key
messages: .item.value.messages
- kind: cursor-team-skill-usage
selector:
query: 'true'
startDate: 30d
endDate: 0d
port:
entity:
mappings:
identifier: >-
((.event_date + "-" + (.skill_name // "unknown"))
| gsub("[^A-Za-z0-9@_.+:\\\\/='-]"; "_"))
title: ((.skill_name // "unknown") + " - " + .event_date)
blueprint: '"cursorTeamSkillUsage"'
properties:
event_date: (if .event_date then (.event_date + "T00:00:00Z") else null end)
skill_name: .skill_name
usage: .usage
Advanced selector configuration
queryapplies to all Cursor resource kinds and defaults to'true'.startDateis a relative start date in days, for example7d. The default is30d. This cannot exceed 30 days.endDateis a relative end date in days, for example0dfor now. The default is0d.usersis an optional comma-separated list of user emails or user IDs. It is supported oncursor-team-skill-usageand filters skill adoption metrics to the specified users.
Below is an example usage:
- kind: cursor-daily-usage
selector:
query: 'true'
startDate: 7d
endDate: 0d
Filter skill usage to specific users:
- kind: cursor-team-skill-usage
selector:
query: 'true'
startDate: 14d
endDate: 0d
users: alice@example.com,user_abc123
Mapping and examples per resource
To view and test the integration mapping against sample API responses, use the jq playground in your connectors page.
The cursor-team-model-usage, cursor-user-model-usage, and cursor-team-skill-usage kinds rely on the Cursor Analytics API, which is available only on the Cursor Enterprise tier. Add these kinds to your mapping only if your Cursor license includes Enterprise analytics access.
{
"identifier": "cursorDailyUsage",
"description": "Daily team usage metrics from Cursor Admin API",
"title": "Cursor Daily Usage",
"icon": "Cursor",
"schema": {
"properties": {
"day": {
"type": "string",
"format": "date-time",
"title": "Day"
},
"user_id": {
"type": "string",
"title": "User ID"
},
"email": {
"type": "string",
"title": "User Email",
"format": "email"
},
"is_active": {
"type": "boolean",
"title": "Active"
},
"total_lines_added": {
"type": "number",
"title": "Total Lines Added"
},
"total_lines_deleted": {
"type": "number",
"title": "Total Lines Deleted"
},
"accepted_lines_added": {
"type": "number",
"title": "Accepted Lines Added"
},
"accepted_lines_deleted": {
"type": "number",
"title": "Accepted Lines Deleted"
},
"total_applies": {
"type": "number",
"title": "Total Applies"
},
"total_accepts": {
"type": "number",
"title": "Total Accepts"
},
"total_rejects": {
"type": "number",
"title": "Total Rejects"
},
"composer_requests": {
"type": "number",
"title": "Composer Requests"
},
"chat_requests": {
"type": "number",
"title": "Chat Requests"
},
"agent_requests": {
"type": "number",
"title": "Agent Requests"
},
"most_used_model": {
"type": "string",
"title": "Most Used Model"
},
"total_tabs_shown": {
"type": "number",
"title": "Total Tabs Shown"
},
"total_tabs_accepted": {
"type": "number",
"title": "Total Tabs Accepted"
},
"subscription_included_reqs": {
"type": "number",
"title": "Subscription Included Requests"
},
"api_key_reqs": {
"type": "number",
"title": "API Key Requests"
},
"usage_based_reqs": {
"type": "number",
"title": "Usage-based Requests"
},
"bugbot_usages": {
"type": "number",
"title": "Bugbot Usages"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {
"acceptance_rate": {
"title": "Acceptance Rate",
"description": "Accepted AI suggestions as a percentage of accepted + rejected suggestions",
"calculation": "if (.properties.total_accepts + .properties.total_rejects) > 0 then (.properties.total_accepts / (.properties.total_accepts + .properties.total_rejects)) * 100 else 0 end",
"type": "number"
}
},
"aggregationProperties": {},
"relations": {}
}
- kind: cursor-daily-usage
selector:
query: 'true'
startDate: 30d
endDate: 0d
port:
entity:
mappings:
identifier: (.userId + "-" + .day)
title: (.email + " " + .day)
blueprint: '"cursorDailyUsage"'
properties:
day: (if .day then (.day + "T00:00:00Z") else null end)
user_id: .userId
email: .email
is_active: .isActive
total_lines_added: .totalLinesAdded
total_lines_deleted: .totalLinesDeleted
accepted_lines_added: .acceptedLinesAdded
accepted_lines_deleted: .acceptedLinesDeleted
total_applies: .totalApplies
total_accepts: .totalAccepts
total_rejects: .totalRejects
total_tabs_shown: .totalTabsShown
total_tabs_accepted: .totalTabsAccepted
composer_requests: .composerRequests
chat_requests: .chatRequests
agent_requests: .agentRequests
most_used_model: .mostUsedModel
subscription_included_reqs: .subscriptionIncludedReqs
api_key_reqs: .apiKeyReqs
usage_based_reqs: .usageBasedReqs
bugbot_usages: .bugbotUsages
{
"date": 1778371200000,
"day": "2026-05-10",
"userId": "user_LGgY21zt4XsBFMZYi2VpfNdAUv",
"email": "dev@getport.io",
"isActive": true,
"totalLinesAdded": 27,
"totalLinesDeleted": 28,
"acceptedLinesAdded": 27,
"acceptedLinesDeleted": 28,
"totalApplies": 2,
"totalAccepts": 2,
"totalRejects": 0,
"totalTabsShown": 1,
"totalTabsAccepted": 0,
"composerRequests": 0,
"chatRequests": 0,
"agentRequests": 11,
"cmdkUsages": 0,
"subscriptionIncludedReqs": 11,
"apiKeyReqs": 0,
"usageBasedReqs": 0,
"bugbotUsages": 0,
"mostUsedModel": "claude-4.6-sonnet-medium-thinking",
"applyMostUsedExtension": "py",
"tabMostUsedExtension": "py",
"clientVersion": "3.1.17"
}
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.
Migration guide
If you currently ingest Cursor metrics through a custom Ocean integration, migrate to the dedicated Cursor integration:
- Create the new Cursor connector from your connectors page.
- Copy your existing Cursor API credentials into the new integration setup.
- Replace legacy custom kinds with the native kinds:
cursor-daily-usage,cursor-usage-event,cursor-team-model-usage,cursor-user-model-usage, andcursor-team-skill-usage. - Run a sync and validate that records are ingested for all enabled resources.
- Disable the legacy custom Ocean Cursor integration after validation.
Related pages
- Skills usage analytics: high-level guide to analyzing skill adoption across Cursor and Claude.
- Visualize Cursor metrics: dashboards for Cursor adoption and impact.