> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Cursor

Loading version...

Port's Cursor integration allows you to ingest daily usage, usage events, and model usage analytics into your software catalog.

Supported resources cursor-daily-usagecursor-usage-eventcursor-team-model-usagecursor-user-model-usage

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.

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

Advanced selector configuration​

  • query applies to all Cursor resource kinds and defaults to 'true'.
  • startDate is a relative start date in days, for example 7d. The default is 30d. This cannot exceed 30 days.
  • endDate is a relative end date in days, for example 0d for now. The default is 0d.

Below is an example usage:

- kind: cursor-daily-usage
  selector:
    query: 'true'
    startDate: 7d
    endDate: 0d

Mapping and examples per resource​

To view and test the integration mapping against sample API responses, use the jq playground in your data sources page.

Cursor Enterprise required for analytics kinds

The cursor-team-model-usage and cursor-user-model-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.

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:

  1. Create the new Cursor data source from your data sources page.
  2. Copy your existing Cursor API credentials into the new integration setup.
  3. Replace legacy custom kinds with the native kinds: cursor-daily-usage, cursor-usage-event, cursor-team-model-usage, and cursor-user-model-usage.
  4. Run a sync and validate that records are ingested for all enabled resources.
  5. Disable the legacy custom Ocean Cursor integration after validation.

Visualize Cursor metrics