Cursor cloud agents
Port's Cursor Cloud Agents integration surfaces your Cursor cloud agents and their runs in your Context Lake. From there, you can launch new agents or send follow-up prompts to existing ones directly from Port workflows.
Trigger a Cursor cloud agent
Use this workflow to send a follow-up prompt to an existing Cursor cloud agent. See the Cursor Cloud Agents integration action page for the full node field reference.
Create a Cursor cloud agent
Use this workflow to let platform engineers or developers launch a new Cursor cloud agent through a self-service form. See the Cursor Cloud Agents integration action page for the full node field reference.
Launching a new Cursor cloud agent always starts a run and billable work immediately. See Action semantics on the integration action page for details.
Prerequisites
- A Cursor API key with access to the Cloud Agents API.
- Optionally configure a webhook signing secret (
webhookSigningSecret) to verify incoming Cursor webhooks. Generate a random string (for exampleopenssl rand -hex 32) and provide it during installation. When unset, webhook signature verification is skipped. - Your Port user role is set to
Admin.
On the Cursor Enterprise plan, you can use a service account API key as the integration's cursor_api_key instead of a personal key. Runs are then attributed to the service account rather than an individual, so the integration keeps working as people and roles change. This requires the Cursor GitHub app to be connected at the team level with the target repositories authorized, and usage bills to your team's usage pool. Note that a service account key cannot reuse a user's saved MCP OAuth logins.
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 the third-party API into Port.
The mapping uses the JQ JSON processor to transform fields and shape incoming Cursor data into Port entities.
Resource selectors
In addition to query, each resource supports optional selector fields in your Port App config:
| Resource | Field | Default | Description |
|---|---|---|---|
agent | includeArchived | false | Include archived agents from Cursor's List Agents API. |
run | includeArchived | false | Include archived agents when fanning out to List Runs (Cursor has no separate archived filter on List Runs). |
run | enrichRunsWithUsage | true | Fetch token usage per agent and merge it into each run during sync. Set to false to skip usage API calls. |
run | oldestRunDate | unset | ISO 8601 UTC timestamp. Stop paginating runs for each agent once a run older than this cutoff is reached (runs are newest-first). |
Example with a run sync window and usage enrichment disabled:
resources:
- kind: agent
selector:
query: 'true'
includeArchived: false
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"cursor_agent"'
- kind: run
selector:
query: 'true'
includeArchived: false
enrichRunsWithUsage: false
oldestRunDate: "2026-01-01T00:00:00Z"
port:
entity:
mappings:
identifier: .id
title: .id
blueprint: '"cursor_run"'
Webhook configuration
Cursor's v0 API attaches a webhook per agent at launch time - there is no account-wide webhook subscription to configure in a Cursor console. On create_agent, set apiVersion to v0 and reportCompletion to true; the integration then attaches a per-run callback URL as the agent's webhook when it launches it. trigger_agent follow-ups always use the v1 API but still receive completion callbacks on agents that were v0-created with a webhook.
<base_url>/integration/webhook/<run_id>
Where <base_url> is:
- Hosted by Port: the live events base URL shown in the install step above.
- Self-hosted: the
liveEvents.baseUrlyou configured during installation.
Optionally configure webhookSigningSecret on the integration (a sensitive installation setting). When set, the integration derives a per-run signing secret from that value, your organization ID, and the run ID embedded in the callback URL, and validates the X-Webhook-Signature header on incoming webhooks. When unset, signature verification is skipped.
Configure webhookSigningSecret so incoming webhooks are authenticated. Without it, any caller that knows your callback URL can post status updates.
Generate a value with for example:
openssl rand -hex 32
Store it as an organization secret during SaaS installation, or set OCEAN__INTEGRATION__CONFIG__WEBHOOK_SIGNING_SECRET for self-hosted deployments.
Default mapping configuration
Default mapping configuration (Click to expand)
resources:
- kind: agent
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"cursor_agent"'
properties:
status: .status
url: .url
repoUrls: |
[.repos[]?.url // empty]
| map(select(. != null and . != ""))
| map(if startswith("http") then . else "https://" + . end)
| map(select(test("^https?://.+")))
createdAt: .createdAt
updatedAt: .updatedAt
- kind: run
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .id
blueprint: '"cursor_run"'
properties:
status: .status
durationMs: .durationMs
branches: '[.git.branches[]?.branch | select(. != null and . != "")] // []'
prUrls: '[.git.branches[]?.prUrl? | select(. != null)] // []'
inputTokens: .usage.inputTokens
outputTokens: .usage.outputTokens
cacheReadTokens: .usage.cacheReadTokens
cacheWriteTokens: .usage.cacheWriteTokens
totalTokens: .usage.totalTokens
createdAt: .createdAt
updatedAt: .updatedAt
relations:
agent: .agentId
Mapping & examples per resource
To view and test the integration mapping against sample API responses, use the jq playground in your data sources page.
Cursor's List Runs and Get Run endpoints don't return token usage inline. When enrichRunsWithUsage is true (the default), the integration makes one extra request per agent to Cursor's usage endpoint and merges each run's usage into its payload before mapping, so the usage field shown in the sample payload below isn't present in Cursor's own List Runs response. Set enrichRunsWithUsage to false on the run resource to skip those calls.
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.