OpenTelemetry Export

OpenTelemetry Export streams Cursor usage data for your team to a collector you run. Cursor sends metrics (tokens, tool calls, best-effort cost) and logs (API requests, errors, corrections, skills, hooks, plugins, cloud agent lifecycle events, and recorded Grok Bot actions) to one team-managed destination. Teams can also opt in to conversation content: the user prompts and assistant responses from Cloud Agents and Grok Bot. Export runs server-side.

OpenTelemetry Export is available on the Enterprise plan. Admins configure it in Team Settings > OpenTelemetry Export.

The Wire Reference documents every metric, log event, and attribute.

Prerequisites

• An HTTPS endpoint that accepts OTLP/HTTP protobuf on /v1/metrics and /v1/logs. Datadog Agent OTLP ingest, the OpenTelemetry Collector, and ClickHouse/ClickStack all work.
• A bearer token or API key Cursor can send as a request header.
• The endpoint must be reachable from the public internet. Cursor egresses from a fixed set of source IPs.

Source IPs

Cursor delivers OTLP through a server-side egress proxy. Traffic originates from these static addresses (all /32):

These IPs don't rotate without advance notice. Use TLS and auth as the primary control. Add IP allowlisting if your network requires it.

Collector recipes

Cursor pushes to your collector over OTLP/HTTP binary protobuf. gRPC and JSON are not supported. Enter the HTTPS base URL in Team Settings without a /v1 suffix; Cursor appends /v1/metrics and /v1/logs.

Minimal OpenTelemetry Collector

receivers:  otlp:    protocols:      http:        endpoint: 0.0.0.0:4318processors:  batch:exporters:  # Swap for your sink (datadog, clickhouse, logging, etc.)  logging:    verbosity: basicservice:  pipelines:    metrics:      receivers: [otlp]      processors: [batch]      exporters: [logging]    logs:      receivers: [otlp]      processors: [batch]      exporters: [logging]

Terminate TLS in front of the collector with a load balancer, ingress, or the otelcol TLS settings. Enter https://otel.example.com in Cursor, not https://otel.example.com:4318/v1. For auth, terminate at the load balancer or configure a static header for Cursor to send, such as Authorization: Bearer <token>.

Datadog Agent (OTLP ingest)

Enable OTLP HTTP ingest and logs in the Agent, then expose the Agent (or a gateway in front of it) over HTTPS:

logs_enabled: trueotlp_config:  receiver:    protocols:      http:        endpoint: 0.0.0.0:4318  logs:    enabled: true

The env-var equivalents are DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318, DD_LOGS_ENABLED=true, and DD_OTLP_CONFIG_LOGS_ENABLED=true. Expose port 4318, or terminate TLS on 443 and proxy to 4318.

In Cursor, the base URL is the public https:// endpoint in front of that listener. Add DD-API-KEY or site headers only if your gateway expects them; the Agent already has api_key configured locally.

See OTLP ingest in the Datadog Agent for Agent configuration details.

Databricks and warehouse-style sinks

For warehouse destinations like Databricks or ClickHouse, run a collector with an OTLP HTTP receiver and the vendor exporter, or forward over HTTP into your ingest pipeline. The Cursor side is the same: an HTTPS base URL serving protobuf on /v1/metrics and /v1/logs. Consume metrics as sums of deltas and dedupe logs on cursor.event.id.

Enable

In Team Settings > OpenTelemetry Export:

1. Create destination with the base URL (no /v1/...; Cursor appends the paths) and auth headers
2. Test connection to check the URL and auth
3. Enable. Export starts within about a minute.

Each signal and telemetry family has its own toggle. New families default on unless you turn off auto_enable_new_families. Conversation content is the exception: it stays off until you enable it.

Conversation content

The conversation_content family streams the text of user prompts and assistant responses to your collector as cursor.conversation.user_message and cursor.conversation.assistant_message logs. Today it covers Cloud Agents and Grok Bot conversations only. IDE, CLI, and desktop conversations are not on this family yet. It is the only family that carries message text. The Wire Reference documents the record shape.

What ships once both controls are on:

• Two log events. cursor.conversation.user_message carries a user prompt and cursor.conversation.assistant_message carries the final assistant response. The event name identifies the role. The body is the message text.
• Scrubbed and capped. Cursor scrubs message text before export and caps each body at 32 KiB. cursor.conversation.content_truncated is true when a message hit the cap.
• Opaque ids only. Records carry the same ids as other logs. No user.email appears on the wire. The only user identifier is the optional, opaque cursor.user.id resource attribute.
• Cloud Agents and Grok Bot only. Cloud Agent conversations arrive as cursor.surface=cloud_agent and Grok Bot conversations as cursor.surface=grok_bot. IDE, CLI, and desktop conversations are not exported by this family yet. Grok Bot messages are separate from the grok_bot_agent_actions family, which needs Action Recording and carries actions rather than messages.

What Cursor exports

Scope: cursor.telemetry 0.1.0.

Everything below is on by default for a new destination, except conversation_content. Turn individual families off in Team Settings.

Metrics (delta temporality)

• cursor.token.usage: by cursor.token.type (input / output / cache_read / cache_creation)
• cursor.tool.calls: builtin and MCP (cursor.tool.kind)
• cursor.cost.usage: best-effort USD estimate, not an invoice

Logs

• cursor.api.request: model call summary
• cursor.api.error: error event (no raw messages)
• cursor.api.correction: billing finalization; join on cursor.usage_event.id
• cursor.skill.activated
• cursor.hook.execution_complete
• cursor.plugin.installed
• cursor.cloud_agent.setup: started / completed / failed
• cursor.cloud_agent.artifact
• cursor.cloud_agent.pull_request: opened / creation_failed
• cursor.cloud_agent.mcp_auth_error: an MCP server rejected the run's credentials
• cursor.grok_bot.mcp_tool_call: a Grok Bot connector (MCP) tool call
• cursor.grok_bot.shell_command: a Grok Bot shell command, secrets scrubbed
• cursor.grok_bot.browser_navigation: a page the Grok Bot browser navigated to
• cursor.grok_bot.computer_use_session: a Grok Bot computer use session summary
• cursor.conversation.user_message: a user prompt, scrubbed; opt-in
• cursor.conversation.assistant_message: an assistant response, scrubbed; opt-in

The cursor.grok_bot.* events carry Action Recording data, so they flow only after a team admin enables Action Recording on the dashboard Grok Bot page. Events are sanitized before export: shell commands are secret-scrubbed and browser URLs are stripped of query strings and fragments.

The cursor.conversation.* events carry message text and flow only after the team opts in and the destination enables the family. See Conversation content.

Families (admin toggles; all default on except conversation_content)

• model_usage: token and cost metrics; api.request / api.error / api.correction
• tool_calls: tool.calls metric
• skills_hooks_plugins: skill / hook / plugin logs
• cloud_agents: cloud_agent.* logs
• grok_bot_agent_actions: grok_bot.* action logs; requires Action Recording (Enterprise)
• conversation_content: conversation.* message logs; off by default

Useful attributes

• Resource: service.name=cursor, cursor.team.id, optional cursor.user.id, surface/entrypoint. Grok Bot traffic exports as cursor.surface=grok_bot across all families; desktop no longer includes it.
• Logs: cursor.event.id (dedupe), and cursor.request.id / cursor.conversation.id / cursor.usage_event.id when present

Delivery

• Metrics are at-most-once. Delta sums can have brief gaps after a failure.
• Logs are at-least-once. Dedupe on cursor.event.id for exactly-once views.
• There is no backfill from before the destination existed.
• Editing the endpoint or credentials keeps the destination. Disabling or deleting it drops in-flight data.

Auth

Cursor stores headers encrypted. To rotate credentials, edit the destination and save. Changes take effect in about 30 seconds.

Limitations

• Cost is not billing. cursor.cost.usage is a best-effort estimate. One series covers both included-quota drawdown and on-demand usage. For BYOK it reflects the Cursor Token Rate only, not provider spend. Use the Admin and billing APIs for invoices.
• Disabling or deleting a destination drops in-flight data. Rotate credentials by editing the destination instead of deleting and re-adding it.
• Logs can arrive more than once. Delivery is at-least-once. Dedupe on cursor.event.id.
• No prompt content unless you opt in. Message text ships only through the opt-in conversation_content family. Every other log event carries ids, counts, and low-cardinality attributes. See Conversation content.
• No trace context or historical backfill. Exported logs don't carry OpenTelemetry trace_id or span_id fields, and Cursor doesn't send traces. Export starts when you enable the destination.
• Metric datapoints carry no correlation IDs. Use log attributes for per-conversation joins. See Joining sessions.
• Metrics are delta-only. Sum deltas per series. A strict delta-to-cumulative processor may drop end-time-inverted points.

Joining sessions

Metrics (cursor.token.usage, cursor.tool.calls, cursor.cost.usage) are aggregates. Datapoints carry no conversation.id, request.id, or usage_event.id. This keeps metric cardinality bounded. For session- or request-scoped analysis, use logs.

What each id means

• cursor.conversation.id is the session key. In the IDE and CLI it's the composer chat UUID. For cloud agents it's the customer-visible bc-... agent id. For grok_bot.* logs it identifies the Bot. The same value appears on that run's api.request, api.error, skill.activated, hook.execution_complete, cloud_agent.*, grok_bot.*, and (when the team opts in) conversation.* logs when present.
• cursor.usage_event.id is the request-grain key on api.request, api.error, and api.correction. Use it to reconcile against Cursor usage and billing exports and to apply corrections.
• cursor.request.id is an optional per-call id on most logs. It never appears on api.correction, cloud_agent.*, or grok_bot.*.
• cursor.event.id is a dedupe key only, not a join key across event types.

Group Grok Bot activity

cursor.grok_bot.turn.id appears on grok_bot.* Action Recording logs. It does not appear on api.request, so model requests join to Grok Bot activity per Bot, not per turn. cursor.user.id is an optional opaque id. Don't require it on every record. Subagents use their own cursor.conversation.id; parent rollup is not exported.

For example, a turn can produce these records:

Group the grok_bot.* records by turn-1 to reconstruct the recorded actions from the turn. Group all four records by bot-a to combine model requests and actions for the Bot. These fields are custom log attributes, not OpenTelemetry trace or span ids.

With conversation content enabled, the Bot's cursor.conversation.user_message and cursor.conversation.assistant_message logs carry the same cursor.conversation.id (bot-a). Join on it to place the prompt and response next to the Bot's model requests and recorded actions. Message logs carry their own optional cursor.conversation.turn.id. Don't depend on cursor.grok_bot.turn.id or cursor.request.id on them.

Recipe: rank sessions by tokens, then attach skills and tools

1. Take cursor.api.request log rows. Sum cursor.api.request.input_tokens and output_tokens (and the cache fields if you need them) grouped by cursor.conversation.id. This gives per-session token totals, which metrics can't provide.
2. Rank conversations by that sum, or by estimated cost.
3. Left-join other logs on the same cursor.conversation.id:
   • cursor.skill.activated shows which skills ran
   • cursor.hook.execution_complete shows hooks
   • cursor.cloud_agent.* shows setup, pull requests, artifacts, and MCP auth failures (cloud agents only)
   • cursor.conversation.user_message and cursor.conversation.assistant_message show the prompts and responses (Cloud Agents and Grok Bot, only with the conversation_content opt-in)
4. cursor.tool.calls is metric-only, so it has no conversation id. Report org-wide tool rates from the metric. Per-session tool attribution is not on the wire yet.

cursor.cost.usage is also metric-only. To rank sessions by cost, approximate from api.request token totals and your own rates, or pull spend from the Admin and billing APIs and join on cursor.usage_event.id where available.

Recipe: apply a billing correction

1. Find cursor.api.correction logs.
2. Join on cursor.usage_event.id to the api.request and api.error logs sharing that id.
3. Treat the whole group as not billed.

Caveats

• Subagents get their own conversation id. Parent rollup is not exported yet.
• Dedupe log rows on cursor.event.id before joining if you need exactly-once views.

Change policy

New metrics and events may appear as coverage expands. auto_enable_new_families controls whether they turn on automatically. Renames and removals get explicit notice. The Wire Reference documents the full attribute surface.