Sitelet https://cursor.com/es/docs/account/organizations/organization-admin-api
Skip to main content

Command Palette

Search for a command to run...

API

API de organización

La API de organización te permite realizar acciones que se aplican a todos los equipos vinculados a una organización, como mover usuarios entre esos equipos, generar informes sobre el uso agrupado en todos los equipos, administrar los grupos de la organización, consultar o actualizar el acceso a modelos y administrar las computadoras del Bot de Grok de los miembros. Usa una clave de API de organización y los mismos patrones HTTP que la API de administración de equipos.

  • La API de organización usa autenticación Basic con tu clave de API como nombre de usuario.
  • Para más información sobre cómo crear claves de API, los métodos de autenticación, los límites de uso y las mejores prácticas, consulta la descripción general de la API.

Claves de API de organización vs. claves de API de equipo

Las claves de API de organización son credenciales con alcance a nivel de organización. Las claves de API de equipo son credenciales con alcance a nivel de equipo.

Usa una clave de API de organización para llamar a endpoints a nivel de organización, como /organizations/team-memberships/sync, /organizations/pooled-usage y /organizations/groups.

Usa una clave de API de equipo para llamar a endpoints bajo /teams/* (por ejemplo, /teams/members y /teams/spend).

Diferencias clave

  • Alcance: Las claves de API de organización pueden operar en todos los equipos asociados a la misma organización. Las claves de API de equipo solo pueden operar dentro de un equipo.
  • Compatibilidad de endpoints: Los endpoints de organización requieren claves de API de organización. Los endpoints de equipo requieren claves de API de equipo.
  • Alcances de la clave: Cada ruta requiere un alcance específico en la clave. Las rutas de membresía de solo lectura aceptan members:read; las rutas de escritura de membresía y grupos necesitan members:*; las rutas de consumo necesitan usage:*. Las claves con admin:* funcionan en todas partes porque el alcance de administrador incluye los demás alcances. Las operaciones de la computadora del Bot de Grok solo aceptan admin:*.
  • Fallos de autorización: Si el alcance de la clave no coincide con el del endpoint, las solicitudes fallan con errores de autenticación o autorización (normalmente 401 o 403).

Alcances

Cada clave de API de organización tiene exactamente un alcance. Una ruta solo se puede usar cuando el alcance de la clave la abarca. Los alcances más amplios incluyen todo lo que permiten los más específicos.

AlcanceAccesoRutas de ejemplo
members:readAcceso de solo lectura a la membresía de la organización.GET /organizations/members
members:*Acceso de lectura y escritura a la membresía y grupos. Incluye todo lo que permite members:read.GET /organizations/members, POST /organizations/team-memberships/sync, todas las rutas de /organizations/groups
usage:*Acceso de lectura al uso agrupado y a los informes.POST /organizations/pooled-usage, POST /organizations/filtered-usage-events, POST /organizations/daily-usage-data, POST /organizations/spend
models:readAcceso de solo lectura a la configuración de acceso a modelos y a los inventarios de proveedores.GET /organizations/teams/model-access/configuration, GET /organizations/teams/{teamId}/model-access/configuration, GET /organizations/teams/{teamId}/model-access/providers
models:*Acceso de lectura y escritura al acceso a modelos. Incluye todo lo que permite models:read.Todas las rutas de acceso a modelos, incluidos los controles masivos de proveedores y modelos y la configuración masiva
auditlogs:readAcceso de solo lectura al feed del registro de auditoría de la organización.GET /organizations/audit-logs
admin:*Acceso completo a todas las rutas de la organización. Es el único alcance que puede ejecutar operaciones de la computadora del Bot de Grok.Todo lo anterior, además de todas las rutas de /organizations/teams/{teamId}/grok-bot/operations

Elige el alcance más específico para la tarea. Usa members:read para integraciones de solo lectura que listan miembros, pero nunca modifican su membresía. Usa models:read o models:* para automatizar el acceso a modelos sin otorgar acceso completo de administrador. Puedes seleccionar estos alcances al crear una clave de API de organización en el Panel de control.

¿Cómo debo enviar una clave de API de organización?

Envíala de la misma forma que otras claves de API de Cursor: autenticación básica con la clave como nombre de usuario y una contraseña vacía.

curl -X POST https://api.cursor.com/organizations/team-memberships/sync \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123",    "users": [      { "userId": 12345, "destinationTeamId": 7 }    ]  }'

Miembros

Consulta la membresía de la organización y mueve miembros entre los equipos vinculados a tu organización.

Listar los miembros de la organización

GET/organizations/members

Obtiene los miembros de la organización asociada a tu clave de API, junto con el rol de organización de cada miembro y sus asignaciones en los equipos vinculados. Los resultados se paginan.

Parámetros de consulta

page number

Número de página (indexado desde 1). El valor predeterminado es la primera página.

pageSize number

Número de miembros por página. El máximo es 200; los valores superiores a 200 se ajustan a 200.

teamId number

Devuelve solo los miembros de este equipo. Si el equipo no está vinculado a la organización, se devuelve una página vacía.

Campos de la respuesta

members array

Array de objetos de miembro de la organización, cada uno con lo siguiente:
  • id number - ID de usuario numérico del miembro, que coincide con el id devuelto por el endpoint de equipo GET /teams/members
  • email string - Dirección de correo electrónico del miembro
  • name string - Nombre para mostrar del miembro
  • organizationRole string - Rol a nivel de organización: admin o member. Es distinto del teamRole de cada asignación de equipo: un usuario puede ser admin de la organización y tener el rol member en un equipo específico, o viceversa.
  • teams array - Asignaciones del miembro en los equipos vinculados a la organización. Cada objeto contiene:
    • teamId number - ID entero de un equipo vinculado al que pertenece el miembro
    • teamRole string - Rol dentro de ese equipo (p. ej., member, owner)

pagination object

Metadatos de paginación: page, pageSize, totalCount, totalPages, hasNextPage y hasPreviousPage.
curl -X GET "https://api.cursor.com/organizations/members?page=1&pageSize=50" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "members": [    {      "id": 12345,      "email": "developer@company.com",      "name": "Alex",      "organizationRole": "member",      "teams": [        { "teamId": 7, "teamRole": "member" },        { "teamId": 8, "teamRole": "owner" }      ]    },    {      "id": 12346,      "email": "admin@company.com",      "name": "Sam",      "organizationRole": "admin",      "teams": [        { "teamId": 7, "teamRole": "owner" }      ]    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

Sincronizar membresías de equipo de la organización

POST/organizations/team-memberships/sync

Establece los equipos a los que pertenecen uno o más usuarios dentro de tu organización. Esto sigue el estilo masivo de la API de importación CSV: envías un array de usuarios y recibes una fila de resultado por cada uno.

Cada entrada debe usar exactamente uno de teamIds o destinationTeamId:

  • teamIds es el conjunto completo de ID de equipo a los que debe pertenecer el usuario. El endpoint ajusta las membresías del usuario exactamente a ese conjunto. Añade cualquier equipo de la lista del que el usuario aún no forme parte y elimina cualquier equipo que no figure en la lista. Para mantener a un usuario en su equipo actual mientras se añade otro durante una migración, incluye ambos (por ejemplo, [oldTeamId, newTeamId]).
  • destinationTeamId asigna al usuario a un único equipo. Se le asigna al equipo especificado y se le elimina de todos los demás equipos. Establecer destinationTeamId: NNN es funcionalmente equivalente a teamIds: [NNN].

Cuerpo de la solicitud

organizationId string Obligatorio

ID público de la organización (por ejemplo, org_abc123). Debe coincidir con la organización asociada a la clave de API de la Organización utilizada para llamar al endpoint.

users array Obligatorio

Lista no vacía de entradas (como máximo 500 por solicitud). Cada elemento es un objeto con un ID de usuario y exactamente un campo de equipo (teamIds o destinationTeamId):
  • userId number | string: ID del usuario que se sincronizará. Acepta un ID numérico entero (por ejemplo, 12345) o un ID de texto (por ejemplo, "user_abc123").
  • teamIds number[]: El conjunto completo de ID de equipo vinculados a la Org a los que debe pertenecer el usuario después de la sincronización. Las membresías se ajustan exactamente a este conjunto. Se elimina cualquier equipo que no figure en la lista. Incluye los equipos actuales del usuario para conservarlos (por ejemplo, [7, 8]). Máximo 100 equipos por entrada.
  • destinationTeamId number: Campo para sincronizar con un único equipo. Establecer destinationTeamId: NNN equivale a enviar teamIds: [NNN]. Los equipos del usuario pasan a ser exactamente ese único equipo. Debe ser un equipo vinculado a la organización.
Proporcione exactamente uno de teamIds o destinationTeamId por entrada.

Respuesta exitosa (HTTP 200)

results array

Una entrada por sincronización solicitada, en orden. Cada objeto incluye userId, los teamIds resueltos para esa entrada, y status: "success" o status: "error" con errorMessage cuando esa fila falla. Las entradas enviadas con destinationTeamId también devuelven destinationTeamId (el primer equipo en teamIds).

successCount number

Número de filas con status: "success".

errorCount number

Número de filas con status: "error".
curl -X POST https://api.cursor.com/organizations/team-memberships/sync \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123",    "users": [      { "userId": 12345, "teamIds": [7, 8] },      { "userId": "user_abc123", "destinationTeamId": 8 }    ]  }'

La primera entrada vincula al usuario 12345 exactamente con los equipos 7 y 8 (añadiendo cualquier equipo en el que el usuario aún no esté y eliminando cualquier otro equipo vinculado). La segunda entrada usa destinationTeamId, que equivale a enviar teamIds: [8].

Response:

{  "results": [    {      "userId": 12345,      "teamIds": [7, 8],      "status": "success"    },    {      "userId": "user_abc123",      "teamIds": [8],      "destinationTeamId": 8,      "status": "success"    }  ],  "successCount": 2,  "errorCount": 0}

Respuestas de error:

La mayoría de los errores de API que se devuelven usan HTTP 401, 403 o 400 y un cuerpo JSON con una estructura como:

{  "code": "error",  "message": "…"}

404: organización no encontrada (esta ruta usa un nombre de campo distinto para el mensaje):

{  "error": "Organization not found"}

401: clave de API de organización no válida (clave incorrecta o ausente):

{  "code": "error",  "message": "Invalid Organization API Key"}

401: falta el alcance requerido (la clave es válida, pero no incluye members:* o admin:*):

{  "code": "error",  "message": "Organization API key missing required scope: members:*"}

403: la organización no corresponde a la clave (organizationId en el cuerpo no corresponde a la organización de esta clave de API):

{  "code": "error",  "message": "Not authorized"}

400: cuerpo de la solicitud no válido (ejemplos; solo uno corresponde a cada solicitud fallida):

{  "code": "error",  "message": "Request body is required"}
{  "code": "error",  "message": "organizationId is required"}
{  "code": "error",  "message": "users must be a non-empty array"}
{  "code": "error",  "message": "users must not contain more than 500 moves"}

Fallos por fila (HTTP 200): Las reglas de validación o de negocio para una sola entrada se devuelven en results con status: "error" y errorMessage. En los ejemplos de abajo se usa destinationTeamId, por lo que las filas muestran destinationTeamId; las entradas enviadas con teamIds muestran teamIds en su lugar. Los tipos no válidos de userId / destinationTeamId usan 0 para el campo no válido en la fila:

{  "results": [    {      "userId": 0,      "destinationTeamId": 7,      "status": "error",      "errorMessage": "Invalid userId"    }  ],  "successCount": 0,  "errorCount": 1}
{  "results": [    {      "userId": 12345,      "destinationTeamId": 0,      "status": "error",      "errorMessage": "Invalid destinationTeamId"    }  ],  "successCount": 0,  "errorCount": 1}
{  "results": [    {      "userId": 0,      "destinationTeamId": 0,      "status": "error",      "errorMessage": "Invalid userId. Invalid destinationTeamId"    }  ],  "successCount": 0,  "errorCount": 1}

Errores por fila (HTTP 200): De la lógica de sincronización cuando las entradas están correctamente tipadas, pero no se puede aplicar el cambio:

{  "results": [    {      "userId": 12345,      "destinationTeamId": 999,      "status": "error",      "errorMessage": "Team is not linked to this organization"    }  ],  "successCount": 0,  "errorCount": 1}
{  "results": [    {      "userId": 12345,      "destinationTeamId": 7,      "status": "error",      "errorMessage": "User is not a member of this organization"    }  ],  "successCount": 0,  "errorCount": 1}
{  "results": [    {      "userId": 12345,      "destinationTeamId": 7,      "status": "error",      "errorMessage": "User not found"    }  ],  "successCount": 0,  "errorCount": 1}

Consumo

Consulta informes sobre el consumo de todos los equipos vinculados a tu organización. Estos endpoints agregan datos de todos los equipos del pool de la organización, por lo que no necesitas una clave de API de equipo independiente para cada equipo. Para informes de un solo equipo, usa en su lugar los endpoints de consumo de la API de administración de equipos del equipo.

Obtener uso agrupado

POST/organizations/pooled-usage

Obtiene el uso agrupado de la organización: el límite de gasto del pool, el consumo total de toda la organización y un desglose por equipo. Se usa en la sección de uso agrupado del Panel de control. Todos los campos monetarios están en centavos.

Cuerpo de la solicitud

organizationId string Obligatorio

ID público de la organización (por ejemplo, org_abc123). Debe coincidir con la organización de la clave de API de la API de organización usada para llamar al endpoint.

Campos de la respuesta

pool object

Totales a nivel de pool para el período contractual actual:
  • limitCents number - Límite de gasto agrupado de la organización, en centavos
  • usedCents number - Uso agrupado total hasta el momento, en centavos
  • remainingCents number - Presupuesto agrupado restante (limitCents menos usedCents), en centavos
  • contractStartDate string | null - Marca de tiempo ISO 8601 que indica el inicio del período contractual actual, o null cuando no se han establecido fechas de contrato
  • contractEndDate string | null - Marca de tiempo ISO 8601 que indica el final del período contractual actual, o null cuando no se han establecido fechas de contrato

teams array

Desglose del consumo por equipo. La suma de todos los usedCents equivale a pool.usedCents. Cada objeto contiene:
  • teamId number - ID entero de un equipo vinculado a la organización
  • usedCents number - Consumo de este equipo durante el período contractual actual, en centavos
  • budgetLimitCents number | undefined - Tope de presupuesto por equipo en centavos. Solo aparece cuando hay un presupuesto configurado para el equipo.
curl -X POST https://api.cursor.com/organizations/pooled-usage \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123"  }'

Respuesta:

{  "pool": {    "limitCents": 5000000,    "usedCents": 1862340,    "remainingCents": 3137660,    "contractStartDate": "2026-01-01T00:00:00.000Z",    "contractEndDate": "2026-12-31T23:59:59.999Z"  },  "teams": [    {      "teamId": 7,      "usedCents": 1440100,      "budgetLimitCents": 2000000    },    {      "teamId": 8,      "usedCents": 422240    }  ]}

Obtener eventos de uso

POST/organizations/filtered-usage-events

Recupera eventos de uso detallados de los equipos vinculados a tu organización. Este es el equivalente a nivel organizacional del endpoint de equipo /teams/filtered-usage-events: devuelve la misma estructura de evento, y cada evento está etiquetado con su teamId propietario.

Cuerpo de la solicitud

organizationId string Obligatorio

ID público de la organización (por ejemplo, org_abc123). Debe coincidir con la organización de la clave de API de la Organización utilizada para llamar al endpoint.

teamIds number[]

Conjunto opcional de identificadores enteros de equipos a incluir. Cada uno debe pertenecer a la organización. Si se omite, se incluyen todos los equipos del grupo de la organización.

startDate number

Fecha de inicio en milisegundos desde la época. Este límite es inclusivo.

endDate number

Fecha de finalización en milisegundos desde epoch. Este límite es inclusivo.

userId number

Filtrar por un ID de usuario específico.

email string

Filtrar por la dirección de correo electrónico del usuario.

serviceAccountId string

Filtrar por ID de cuenta de servicio.

page number

Número de página (indexado desde 1). Predeterminado: 1

pageSize number

Número de resultados por página. Predeterminado: 10

Campos de respuesta

Cada objeto en usageEvents contiene los mismos campos que el endpoint del equipo, además de una etiqueta del equipo propietario:

  • teamId number - ID entero del equipo propietario de este evento
  • timestamp string - Marca temporal del evento en milisegundos desde la época Unix (como string)
  • userEmail string - Dirección de correo electrónico del usuario que realizó la solicitud
  • serviceAccountId string | undefined - ID de la cuenta de servicio que realizó la solicitud. Se omite en eventos de usuarios humanos.
  • serviceAccountName string | undefined - Nombre visible de la cuenta de servicio que realizó la solicitud. Se omite en los eventos de usuarios humanos.
  • model string - modelo de IA utilizado en la solicitud
  • kind string - Categoría de facturación (p. ej., Basado en consumo, Incluido en el plan Business)
  • maxMode boolean - Si la solicitud usó el modo Max
  • requestsCosts number - coste en unidades de solicitud
  • isTokenBasedCall boolean - Indica si la solicitud se facturó según el consumo de tokens
  • isChargeable boolean - Indica si este evento genera un cargo
  • isHeadless boolean - Indica si esta solicitud se realizó sin un cliente conectado (p. ej., agentes de programación en segundo plano)
  • tokenUsage object | undefined - Información sobre el consumo de tokens (se muestra cuando isTokenBasedCall es true):
    • inputTokens number - Tokens de entrada consumidos
    • outputTokens number - Tokens de salida generados
    • cacheWriteTokens number - Tokens escritos en caché
    • cacheReadTokens number - Tokens leídos de caché
    • totalCents number - Coste total del modelo en centavos
    • discountPercentOff number | undefined - Porcentaje de descuento aplicado, si lo hay
  • chargedCents number - Importe total cobrado en céntimos por este evento. Para las solicitudes a modelos de terceros sujetas a la tasa de tokens de Cursor, esto incluye tanto el coste del modelo como la tasa de tokens de Cursor.
  • cursorTokenFee number | undefined - tasa de tokens de Cursor en centavos. Solo aparece cuando la tasa se aplica a una solicitud a un modelo de terceros (incluido cuando Auto enruta a un modelo de terceros).
# Eventos de todos los equipos del pool de la organizacióncurl -X POST https://api.cursor.com/organizations/filtered-usage-events \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123",    "startDate": 1748411762359,    "endDate": 1751003762359,    "page": 1,    "pageSize": 25  }'# Eventos limitados a equipos específicoscurl -X POST https://api.cursor.com/organizations/filtered-usage-events \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123",    "teamIds": [7, 8],    "startDate": 1748411762359,    "endDate": 1751003762359,    "page": 1,    "pageSize": 25  }'

Respuesta:

{  "totalUsageEventsCount": 113,  "pagination": {    "numPages": 12,    "currentPage": 1,    "pageSize": 10,    "hasNextPage": true,    "hasPreviousPage": false  },  "usageEvents": [    {      "teamId": 7,      "timestamp": "1750979225854",      "userEmail": "developer@company.com",      "model": "claude-4.5-sonnet",      "kind": "Usage-based",      "maxMode": true,      "requestsCosts": 5,      "isTokenBasedCall": true,      "isChargeable": true,      "isHeadless": false,      "tokenUsage": {        "inputTokens": 126,        "outputTokens": 450,        "cacheWriteTokens": 6112,        "cacheReadTokens": 11964,        "totalCents": 20.18232      },      "chargedCents": 21.36232,      "cursorTokenFee": 1.18    },    {      "teamId": 8,      "timestamp": "1750978339901",      "userEmail": "admin@company.com",      "model": "claude-4-sonnet-thinking",      "kind": "Included in Business",      "maxMode": true,      "requestsCosts": 1.4,      "isTokenBasedCall": false,      "isChargeable": false,      "isHeadless": false,      "chargedCents": 8    }  ],  "period": {    "startDate": 1748411762359,    "endDate": 1751003762359  }}

Obtener datos de consumo diario

POST/organizations/daily-usage-data

Recupera las métricas de uso diario de cada miembro en los equipos vinculados a tu organización. Este es el equivalente a nivel de organización del endpoint del equipo /teams/daily-usage-data, con cada fila etiquetada con su teamId propietario. Los resultados están paginados por usuario y devuelven datos de todos los miembros que tuvieron membresía durante el intervalo de fechas solicitado; usa page y pageSize para navegar entre las páginas.

Cuerpo de la solicitud

organizationId string Obligatorio

ID público de la organización (por ejemplo org_abc123). Debe coincidir con la organización de la clave de API de Organización utilizada para llamar al endpoint.

startDate number

Fecha de inicio en milisegundos epoch. El valor predeterminado es hace 7 días.

endDate number

Fecha de finalización en milisegundos epoch. Por defecto es el momento actual.

teamIds number[]

Equipos vinculados a la organización sobre los que informar. Si se omite, se incluyen todos los equipos del grupo de la organización. Máximo 100 equipos por solicitud.

page number

Número de página (indexado desde 1). Predeterminado: 1

pageSize number

Número de usuarios por página (1-1000). Predeterminado: 1000

userEmail string

Filtra uno o más usuarios por correo electrónico. Acepta un único correo electrónico o una lista separada por comas. userEmails se acepta como alias.

Campos de respuesta

Cada objeto del array data contiene los mismos campos que el endpoint de uso diario del equipo, además de un teamId. Campos clave:

  • userId string - ID de usuario codificado con el prefijo user_ (p. ej., user_abc123)
  • teamId número - ID del equipo asociado a la organización al que pertenece esta fila
  • day string - La fecha correspondiente a este registro (fecha ISO, p. ej., 2024-03-18)
  • date número - Fecha en milisegundos desde la época Unix
  • email string - Dirección de correo electrónico del usuario
  • isActive boolean - Indica si el usuario tuvo actividad ese día
  • totalLinesAdded número - Total de líneas de código añadidas
  • totalLinesDeleted número - Total de líneas de código eliminadas
  • acceptedLinesAdded number - líneas añadidas sugeridas por la IA que se aceptaron
  • acceptedLinesDeleted número - Líneas eliminadas sugeridas por IA que se aceptaron
  • totalApplies number - Número total de acciones de aplicación de código con IA
  • totalAccepts número - Número total de sugerencias de IA aceptadas
  • totalRejects número - Total de sugerencias de IA rechazadas
  • totalTabsShown número - Total de sugerencias de Tab completion mostradas al usuario
  • totalTabsAccepted número - Total de Tab completions aceptadas por el usuario
  • composerRequests number - Número de solicitudes realizadas en Composer
  • chatRequests number - Número de solicitudes de chat realizadas
  • agentRequests número - Cantidad de solicitudes realizadas en el Modo Agent
  • cmdkUsages número - Número de consumos de Inline edit con Cmd+K
  • subscriptionIncludedReqs number - Solicitudes incluidas en el plan de suscripción
  • apiKeyReqs number - Solicitudes realizadas con clave de API
  • usageBasedReqs número - Solicitudes basadas en consumo (exceso)
  • bugbotUsages número - Cantidad de consumos de Bugbot
  • mostUsedModel string | null - Modelo de IA más usado del día
  • applyMostUsedExtension string | null - Extensión de archivo más común para las acciones de aplicación
  • tabMostUsedExtension string | null - Extensión de archivo más común en Tab completions
  • clientVersion string | null - versión del cliente de Cursor utilizada

La respuesta también incluye un objeto pagination (page, pageSize, totalUsers, totalPages, hasNextPage, hasPreviousPage) y un objeto period (startDate, endDate).

curl -X POST https://api.cursor.com/organizations/daily-usage-data \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123",    "startDate": 1710720000000,    "endDate": 1710892800000,    "page": 1,    "pageSize": 1000  }'

Respuesta:

{  "data": [    {      "userId": "user_abc123",      "teamId": 101,      "day": "2024-03-18",      "date": 1710720000000,      "isActive": true,      "totalLinesAdded": 1543,      "totalLinesDeleted": 892,      "acceptedLinesAdded": 1102,      "acceptedLinesDeleted": 645,      "totalApplies": 87,      "totalAccepts": 73,      "totalRejects": 14,      "totalTabsShown": 342,      "totalTabsAccepted": 289,      "composerRequests": 45,      "chatRequests": 128,      "agentRequests": 12,      "cmdkUsages": 67,      "subscriptionIncludedReqs": 180,      "apiKeyReqs": 0,      "usageBasedReqs": 5,      "bugbotUsages": 3,      "mostUsedModel": "gpt-5",      "applyMostUsedExtension": ".tsx",      "tabMostUsedExtension": ".ts",      "clientVersion": "0.25.1",      "email": "developer@company.com"    }  ],  "period": {    "startDate": 1710720000000,    "endDate": 1710892800000  },  "pagination": {    "page": 1,    "pageSize": 1000,    "totalUsers": 150,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

Obtener datos de gasto

POST/organizations/spend

Recupera el gasto por miembro en los equipos vinculados a tu organización. Esta es la contraparte a nivel de organización del endpoint de equipo /teams/spend, con cada miembro etiquetado con el teamId de su equipo. A diferencia del endpoint de equipo, el gasto se informa sobre la ventana contractual de la organización (no sobre los ciclos de facturación de cada equipo) usando la misma definición de gasto incluido que /organizations/pooled-usage, por lo que las cifras coinciden con el pool.

Cuerpo de la solicitud

organizationId string Obligatorio

ID público de la organización (por ejemplo, org_abc123). Debe coincidir con la organización de la clave de API de organización usada para llamar al endpoint.

teamIds number[]

Equipos vinculados a la organización sobre los que se informará. Si se omite, se incluyen todos los equipos del pool de la organización. Como máximo, 100 equipos por solicitud.

sortBy string

Ordenar por: email, name, spendCents. Predeterminado: email

sortDirection string

Orden: asc, desc. Predeterminado: asc

page number

Número de página (indexado desde 1). Predeterminado: 1

pageSize number

Resultados por página (1-1000). Predeterminado: 100

Campos de respuesta

Cada objeto de teamMemberSpend contiene:

  • userId string - ID de usuario codificado con el prefijo user_ (p. ej., user_abc123)
  • teamId number - ID del equipo vinculado a la organización al que pertenece este miembro
  • name string - Nombre para mostrar del usuario
  • email string - Dirección de correo electrónico del usuario
  • role string - Rol en el equipo (p. ej., member, owner)
  • spendCents number - Gasto incluido del pool, en centavos, atribuido a este miembro durante la ventana contractual de la organización

La respuesta también incluye totalMembers (number), totalPages (number) y un objeto period (startDate, endDate en milisegundos desde la época Unix) que describe la ventana contractual de la organización.

curl -X POST https://api.cursor.com/organizations/spend \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "organizationId": "org_abc123",    "sortBy": "spendCents",    "sortDirection": "desc",    "page": 1,    "pageSize": 25  }'

Respuesta:

{  "teamMemberSpend": [    {      "userId": "user_abc123",      "teamId": 101,      "name": "Alex",      "email": "developer@company.com",      "role": "member",      "spendCents": 2450    },    {      "userId": "user_def456",      "teamId": 202,      "name": "Sam",      "email": "admin@company.com",      "role": "owner",      "spendCents": 1875    }  ],  "totalMembers": 15,  "totalPages": 1,  "period": {    "startDate": 1735689600000,    "endDate": 1767225600000  }}

Acceso a modelos

Consulta y actualiza la política de acceso a modelos de los equipos vinculados a la organización. Estas rutas corresponden a la API de acceso a modelos de equipos y se limitan a los equipos vinculados.

Usa la lista y las solicitudes GET de cada equipo para detectar desajustes de configuración. Alinea los equipos mediante solicitudes PUT de configuración y activando o desactivando proveedores y modelos (incluidos los parameters de cada modelo). No hay un endpoint de copia ni una huella de política a nivel de organización.

Activar un modelo sin ajustes de parámetros lo deja con los valores predeterminados del catálogo. Usa la ruta masiva de modelos cuando valores predeterminados como Fast no coincidan con la política de tu organización.

Los valores numéricos de teamId se obtienen de rutas como GET /organizations/members.

Listar la configuración de acceso a modelos

GET/organizations/teams/model-access/configuration

Lista la configuración de acceso a modelos de los equipos vinculados. Úsala para detectar desajustes entre políticas sin restricciones y personalizadas. Para detectar desajustes de activación y desactivación, ejecuta GET para los proveedores de cada equipo y compáralos.

Si un equipo vinculado no tiene activado el control de acceso a modelos, esa fila seguirá devolviendo HTTP 200 e incluirá errorMessage en lugar de state / valores predeterminados. Las rutas GET y de escritura por equipo para ese equipo devuelven 403.

Parámetros de consulta

page number

Número de página (indexado desde 1).

pageSize number

Resultados por página.

teamIds string

IDs de equipo opcionales separados por comas; por ejemplo, 7,8,9.
curl -X GET "https://api.cursor.com/organizations/teams/model-access/configuration?page=1&pageSize=50" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "teams": [    {      "teamId": 7,      "teamName": "Platform",      "state": "custom",      "newProviderDefault": "disabled",      "newModelDefault": "enabled"    },    {      "teamId": 8,      "teamName": "Mobile",      "state": "custom",      "newProviderDefault": "disabled",      "newModelDefault": "enabled"    },    {      "teamId": 9,      "teamName": "Data",      "state": "unrestricted",      "newProviderDefault": null,      "newModelDefault": null    },    {      "teamId": 10,      "teamName": "Research",      "errorMessage": "Model access control is not available for this team"    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 4,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

Obtener la configuración de acceso a modelos de un equipo

GET/organizations/teams/:teamId/model-access/configuration

Obtiene la configuración de un equipo vinculado.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.
curl -X GET https://api.cursor.com/organizations/teams/7/model-access/configuration \  -u YOUR_ORGANIZATION_API_KEY:

Actualizar la configuración de acceso a modelos de un equipo

PUT/organizations/teams/:teamId/model-access/configuration

Crea o actualiza la configuración de un equipo vinculado, o restablece ese equipo al acceso sin restricciones. Usa el mismo cuerpo y comportamiento de inicialización que la ruta de equipo.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.

Cuerpo de la solicitud

state string

Opcional. Usa unrestricted para borrar la política. Omítelo al enviar los valores predeterminados.

newProviderDefault string

enabled o disabled. Obligatorio al crear o actualizar una política personalizada; omítelo cuando state sea unrestricted.

newModelDefault string

enabled o disabled. Obligatorio al crear o actualizar una política personalizada; omítelo cuando state sea unrestricted.
curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/configuration \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "newProviderDefault": "disabled",    "newModelDefault": "enabled"  }'

Restablecer un equipo vinculado al acceso sin restricciones:

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/configuration \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{ "state": "unrestricted" }'

Actualización masiva de la configuración de acceso a modelos

PUT/organizations/teams/model-access/configuration

Crea o actualiza la configuración, o restablece el acceso sin restricciones, para varios equipos vinculados. Hasta 100 teamIds por solicitud.

HTTP 200 significa que se procesó el lote, no que todas las filas se hayan procesado correctamente. Revisa errorCount y cada results[].status. Los equipos procesados correctamente conservan su nueva configuración. La operación es idempotente por equipo, así que vuelve a intentarlo solo con los teamId que fallaron. Una respuesta 4xx o 5xx rechaza toda la solicitud y no aplica ningún cambio.

Cuerpo de la solicitud

teamIds number[] Obligatorio

ID de los equipos vinculados que se actualizarán. Máximo 100 por solicitud.

state string

Opcional. Usa unrestricted para eliminar la política de cada equipo. Omítelo al enviar valores predeterminados.

newProviderDefault string

enabled o disabled. Obligatorio al crear o actualizar políticas personalizadas; omítelo si state es unrestricted.

newModelDefault string

enabled o disabled. Obligatorio al crear o actualizar políticas personalizadas; omítelo si state es unrestricted.

Establece los valores predeterminados de una política personalizada para varios equipos:

curl -X PUT https://api.cursor.com/organizations/teams/model-access/configuration \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "teamIds": [7, 8, 9],    "newProviderDefault": "disabled",    "newModelDefault": "enabled"  }'

Restablece el acceso sin restricciones para varios equipos:

curl -X PUT https://api.cursor.com/organizations/teams/model-access/configuration \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "teamIds": [7, 8, 9],    "state": "unrestricted"  }'

Respuesta:

{  "results": [    { "teamId": 7, "status": "success" },    { "teamId": 8, "status": "success" },    {      "teamId": 9,      "status": "error",      "errorMessage": "Team is not linked to this organization"    }  ],  "successCount": 2,  "errorCount": 1}

Obtener proveedores de acceso a modelos de un equipo

GET/organizations/teams/:teamId/model-access/providers

Enumera los proveedores y modelos de un equipo vinculado, incluidos los parameters por modelo (con la misma estructura que la ruta de providers del equipo). Devuelve 409 cuando el equipo no tiene una política personalizada.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.
curl -X GET https://api.cursor.com/organizations/teams/7/model-access/providers \  -u YOUR_ORGANIZATION_API_KEY:

Actualizar proveedor de acceso a modelos de un equipo

PUT/organizations/teams/:teamId/model-access/providers/:provider

Activa o desactiva un proveedor en un equipo vinculado. Devuelve 409 cuando el equipo no tiene una política personalizada.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.

provider string Obligatorio

ID del proveedor en el catálogo (por ejemplo, openai).

Cuerpo de la solicitud

enabled boolean Obligatorio

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/providers/openai \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{"enabled": false}'

Actualizar modelo de acceso a modelos de un equipo

PUT/organizations/teams/:teamId/model-access/providers/:provider/models/:model

Activa o desactiva un modelo en un equipo vinculado y, opcionalmente, configura parameters específicos del modelo (con el mismo cuerpo que la ruta de modelo del equipo). Devuelve 409 cuando el equipo no tiene una política personalizada.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.

provider string Obligatorio

ID del proveedor en el catálogo (por ejemplo, anthropic).

model string Obligatorio

ID del modelo en el catálogo (por ejemplo, claude-opus-4-6).

Cuerpo de la solicitud

enabled boolean Obligatorio

parameters object

Mapa opcional de ID de parámetros a { allowedValues, defaultValue }. Los campos omitidos no se modifican. allowedValues: null elimina una restricción. defaultValue: null restaura el valor predeterminado del catálogo. Consulta la documentación del equipo sobre Actualizar modelo de acceso a modelos.

Desactiva Fast en un equipo vinculado:

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/providers/anthropic/models/claude-opus-4-6 \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "parameters": {      "fast": { "allowedValues": ["false"] }    }  }'

Establece el esfuerzo de razonamiento predeterminado:

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/providers/openai/models/gpt-5.4 \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "parameters": {      "reasoning": {        "allowedValues": ["low", "medium", "high"],        "defaultValue": "high"      }    }  }'

Actualización masiva de proveedores de acceso a modelos

PUT/organizations/teams/model-access/providers/:provider

Activa o desactiva un proveedor en varios equipos vinculados. Hasta 100 teamIds por solicitud.

HTTP 200 significa que se procesó el lote, no que todas las filas se completaron correctamente. Revise errorCount y cada results[].status. Las filas correctas no se revierten. La operación es idempotente por equipo, así que vuelva a intentarlo solo con los teamId fallidos. Una respuesta 4xx o 5xx rechaza toda la solicitud y no aplica ningún cambio.

Parámetros

provider string Obligatorio

ID del proveedor en el catálogo (por ejemplo, openai).

Cuerpo de la solicitud

enabled boolean Obligatorio

teamIds number[] Obligatorio

ID de los equipos vinculados que se actualizarán. Máximo 100 por solicitud.
curl -X PUT https://api.cursor.com/organizations/teams/model-access/providers/openai \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "teamIds": [7, 8, 9],    "enabled": false  }'

Respuesta:

{  "results": [    { "teamId": 7, "status": "success" },    { "teamId": 8, "status": "success" },    {      "teamId": 9,      "status": "error",      "errorMessage": "El equipo no tiene una política de acceso a modelos. Cree una con PUT /teams/model-access/configuration o active el acceso a modelos en ajustes de equipo → Modelos."    }  ],  "successCount": 2,  "errorCount": 1}

En este ejemplo, el estado HTTP sigue siendo 200 porque el lote se completó. Los equipos 7 y 8 mantienen el proveedor desactivado; vuelva a intentarlo solo con el equipo 9 después de crear su configuración.

Actualización masiva del modelo de acceso a modelos

PUT/organizations/teams/model-access/providers/:provider/models/:model

Activa o desactiva un modelo en varios equipos vinculados, opcionalmente con el mismo mapa de parameters que el PUT de modelo para un solo equipo. Hasta 100 teamIds por solicitud.

HTTP 200 indica que se procesó el lote, no que todas las filas se hayan completado correctamente. Revisa errorCount y cada results[].status. Las filas correctas no se revierten. La operación es idempotente para cada equipo, así que vuelve a intentarlo solo para los teamId que fallaron. Una respuesta 4xx o 5xx rechaza toda la solicitud y no aplica cambios.

Parámetros

provider string Obligatorio

ID del proveedor en el catálogo (por ejemplo, anthropic).

model string Obligatorio

ID del modelo en el catálogo (por ejemplo, claude-opus-4-6).

Cuerpo de la solicitud

enabled boolean Obligatorio

teamIds number[] Obligatorio

ID de los equipos vinculados que se actualizarán. Máximo 100 por solicitud.

parameters object

Opcional. El mismo mapa que el PUT de modelo para un solo equipo. allowedValues: null elimina una restricción. defaultValue: null restaura el valor predeterminado del catálogo.

Desactiva Fast en los equipos vinculados:

curl -X PUT https://api.cursor.com/organizations/teams/model-access/providers/anthropic/models/claude-opus-4-6 \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "teamIds": [7, 8, 9],    "enabled": true,    "parameters": {      "fast": { "allowedValues": ["false"] }    }  }'

Fija el esfuerzo de razonamiento predeterminado en los equipos vinculados:

curl -X PUT https://api.cursor.com/organizations/teams/model-access/providers/openai/models/gpt-5.4 \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "teamIds": [7, 8, 9],    "enabled": true,    "parameters": {      "reasoning": {        "allowedValues": ["low", "medium", "high"],        "defaultValue": "high"      }    }  }'

Respuesta:

{  "results": [    { "teamId": 7, "status": "success" },    { "teamId": 8, "status": "success" },    {      "teamId": 9,      "status": "error",      "errorMessage": "El equipo no tiene una política de acceso a modelos. Crea una con PUT /teams/model-access/configuration o activa el acceso a modelos en Ajustes de equipo → Modelos."    }  ],  "successCount": 2,  "errorCount": 1}

Errores

Los cuerpos de los errores usan:

{ "code": "error", "message": "…" }
EstadoCuándo
401Clave incorrecta o falta models:read / models:* (o admin:*)
403El control de acceso a modelos no está disponible para ese equipo (rutas de un solo equipo)
404El equipo no está vinculado a la organización (rutas de un solo equipo)
409Lectura de un proveedor o modelo, o escritura de un solo equipo mientras el state de ese equipo sea unrestricted o legacy
400ID de proveedor, modelo o parámetro, o valor de parámetro desconocido; cuerpo no válido; allowedValues vacío; valor predeterminado fuera de allowedValues; ajustes que no se resuelven en ninguna variante de modelo válida; o se bloquearía un modelo obligatorio de Smart Auto

Las rutas masivas de la organización (PUT .../providers/:provider, PUT .../providers/:provider/models/:model y PUT .../configuration con teamIds) devuelven HTTP 200 cuando se procesa el lote, incluso si algunas filas fallan. Un errorCount distinto de cero sigue siendo una respuesta HTTP exitosa. Los equipos no vinculados y los errores públicos, como la falta de configuración, aparecen como filas status: "error". Las filas correctas no se revierten. Las operaciones son idempotentes por equipo, así que vuelva a intentar solo los teamId que fallaron. Cualquier respuesta 4xx o 5xx significa que se rechazó toda la solicitud y no se aplicaron cambios. La ruta de lista también devuelve HTTP 200 con una fila errorMessage cuando un equipo vinculado no puede cargar la configuración.

Grupos de la organización

Los grupos de la organización organizan a los miembros de los equipos vinculados a una misma organización. Para la configuración en el panel de control y los controles a nivel de grupo, consulta Grupos de la organización. Los directory groups de equipo usan la Team Admin API en /teams/directory-groups y los ids team_group_…. Esas rutas no aceptan valores de id (g_) ni publicId (grp_) de los grupos de la organización.

Las rutas de grupos comparten estas respuestas de error:

StatusCuándo
400ID de grupo, valor de paginación o cuerpo de la solicitud con formato incorrecto
401Clave de API no válida, o la clave no tiene el scope members:* (o admin:*)
404El grupo no existe en la organización
429Límite de uso excedido. La respuesta incluye un header Retry-After: 60

Listar grupos de la organización

GET/organizations/groups

Obtén los grupos de la organización asociada a tu clave de API. Pasa name para buscar un grupo por su nombre exacto.

Parámetros de consulta

page number

Número de página. El valor predeterminado es 1.

pageSize number

Número de grupos por página. El valor predeterminado es 50. El máximo es 200; los valores superiores a 200 se ajustan a 200.

name string

Nombre exacto de un grupo, codificado en URL (por ejemplo, Platform%20Engineering). Los nombres de grupo son únicos dentro de una organización, por lo que la respuesta es el payload de lista habitual con un grupo o ninguno. Un nombre sin coincidencias devuelve 200 con un array groups vacío, no 404. Omite name, o envíalo en blanco, para listar todos los grupos.

Campos de la respuesta

Cada objeto de groups contiene:

  • id string - ID del grupo de la organización con el prefijo g_
  • publicId string - ID público del grupo con el prefijo grp_
  • name string - Nombre del grupo
  • memberCount number - Número de miembros del grupo
  • monthlySpendingLimitDollars number | null - Límite de gasto mensual en dólares enteros para cada miembro del grupo. null significa que el grupo no tiene límite.
  • createdAt string - Fecha de creación en formato ISO 8601
  • updatedAt string - Fecha de la última actualización en formato ISO 8601

pagination object

Metadatos de paginación: page, pageSize, totalCount, totalPages, hasNextPage y hasPreviousPage.
curl -X GET "https://api.cursor.com/organizations/groups?page=1&pageSize=50" \  -u YOUR_ORGANIZATION_API_KEY:

Busca un grupo por nombre:

curl -X GET "https://api.cursor.com/organizations/groups?name=Engineering" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "groups": [    {      "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",      "publicId": "grp_01k2ja2000e0080000000000n2",      "name": "Engineering",      "memberCount": 12,      "monthlySpendingLimitDollars": 500,      "createdAt": "2026-01-15T10:30:00.000Z",      "updatedAt": "2026-01-20T14:22:00.000Z"    },    {      "id": "g_kljUvI0ASZORvSEXf9hV0ydcso",      "publicId": "grp_01k2jb4000e0080000000000p7",      "name": "Design",      "memberCount": 8,      "monthlySpendingLimitDollars": null,      "createdAt": "2026-01-16T09:00:00.000Z",      "updatedAt": "2026-01-16T09:00:00.000Z"    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

Respuesta (búsqueda por nombre):

{  "groups": [    {      "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",      "publicId": "grp_01k2ja2000e0080000000000n2",      "name": "Engineering",      "memberCount": 12,      "monthlySpendingLimitDollars": 500,      "createdAt": "2026-01-15T10:30:00.000Z",      "updatedAt": "2026-01-20T14:22:00.000Z"    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 1,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

Obtener un grupo de la organización

GET/organizations/groups/:groupId

Obtén un grupo de la organización.

Parámetros

groupId string Obligatorio

ID del grupo de la organización con el prefijo g_.

Campos de la respuesta

El objeto group contiene id, publicId, name, memberCount, monthlySpendingLimitDollars, createdAt y updatedAt. Estos campos coinciden con la respuesta de Listar grupos de la organización.

curl -X GET https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "group": {    "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",    "publicId": "grp_01k2ja2000e0080000000000n2",    "name": "Engineering",    "memberCount": 12,    "monthlySpendingLimitDollars": 500,    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-20T14:22:00.000Z"  }}

Crear un grupo de la organización

POST/organizations/groups

Crea un grupo de la organización con membresía gestionada manualmente. Para crear un grupo sincronizado con SCIM, sincronízalo desde tu proveedor de identidad en el panel de control.

Cuerpo de la solicitud

name string Obligatorio

Nombre del grupo. Debe ser único entre los grupos activos de la organización. Cursor elimina los espacios en blanco iniciales y finales.

Campos de la respuesta

Devuelve 201 Created con el nuevo objeto group. El objeto contiene id, publicId, name, memberCount, monthlySpendingLimitDollars, createdAt y updatedAt.

Errores

  • 400 - Falta el nombre del grupo, está vacío o ya lo usa otro grupo activo.
curl -X POST https://api.cursor.com/organizations/groups \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Engineering"  }'

Respuesta:

{  "group": {    "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",    "publicId": "grp_01k2ja2000e0080000000000n2",    "name": "Engineering",    "memberCount": 0,    "monthlySpendingLimitDollars": null,    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-15T10:30:00.000Z"  }}

Actualizar grupo de la organización

PATCH/organizations/groups/:groupId

Actualiza el nombre o el límite de gasto mensual de un grupo. Las actualizaciones son parciales: incluye al menos un campo; los campos que omitas conservan su valor actual.

Parámetros

groupId string Obligatorio

ID del grupo de la organización con el prefijo g_.

Cuerpo de la solicitud

name string

Nuevo nombre del grupo. Debe ser único entre los grupos activos de la organización. Cursor elimina los espacios en blanco iniciales y finales.

monthlySpendingLimitDollars number

Límite de gasto mensual en dólares enteros para cada miembro del grupo, entre 0 y 2147483647.

clearMonthlySpendingLimitDollars boolean

Establécelo en true para eliminar el límite de gasto del grupo. No incluyas monthlySpendingLimitDollars en la misma solicitud.

Campos de la respuesta

Devuelve el objeto group actualizado con id, publicId, name, memberCount, monthlySpendingLimitDollars, createdAt y updatedAt.

Errores

  • 400 - La solicitud no incluye campos para actualizar, contiene un valor no válido, usa el nombre de otro grupo activo, o establece y elimina el límite de gasto en la misma solicitud.
curl -X PATCH https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Platform Engineering",    "monthlySpendingLimitDollars": 500  }'

Respuesta:

{  "group": {    "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",    "publicId": "grp_01k2ja2000e0080000000000n2",    "name": "Platform Engineering",    "memberCount": 12,    "monthlySpendingLimitDollars": 500,    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-20T14:22:00.000Z"  }}

Eliminar un grupo de la organización

DELETE/organizations/groups/:groupId

Elimina un grupo de la organización. El grupo debe estar vacío: quita a todos los miembros antes de eliminarlo.

Parámetros

groupId string Obligatorio

ID del grupo de la organización con el prefijo g_.

Respuesta

Devuelve 204 No Content tras eliminar el grupo.

Errores

  • 400 - El grupo todavía tiene miembros o tiene un mapeo SCIM activo.
curl -X DELETE https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta: 204 No Content

Listar miembros de un grupo de la organización

GET/organizations/groups/:groupId/members

Obtiene los miembros de un grupo de la organización.

Parámetros

groupId string Obligatorio

ID del grupo de la organización con el prefijo g_.

Parámetros de consulta

page number

Número de página. El valor predeterminado es 1.

pageSize number

Número de miembros por página. El valor predeterminado es 50. El máximo es 200; los valores superiores a 200 se ajustan a 200.

Campos de la respuesta

Cada objeto de members contiene:

  • userId string - ID de usuario público con el prefijo user_
  • name string - Nombre visible del miembro
  • email string - Dirección de correo electrónico del miembro
  • joinedAt string - Momento en que se añadió el miembro al grupo, en formato ISO 8601

pagination object

Metadatos de paginación: page, pageSize, totalCount, totalPages, hasNextPage y hasPreviousPage.
curl -X GET "https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy/members?page=1&pageSize=50" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "members": [    {      "userId": "user_abc123",      "name": "Alex Developer",      "email": "alex@company.com",      "joinedAt": "2026-01-15T10:30:00.000Z"    },    {      "userId": "user_def456",      "name": "Sam Engineer",      "email": "sam@company.com",      "joinedAt": "2026-01-16T09:15:00.000Z"    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

Añadir miembros a un grupo de la organización

POST/organizations/groups/:groupId/members/bulk-add

Añade miembros a un grupo de la organización manual.

Parámetros

groupId string Obligatorio

ID del grupo de la organización con el prefijo g_.

Cuerpo de la solicitud

userIds string[] Obligatorio

Array de IDs públicos de usuario con el prefijo user_. Una sola solicitud puede incluir hasta 100 usuarios.

Campos de la respuesta

addedCount number

Número de membresías que ha creado esta solicitud. Cursor ignora a los usuarios ajenos a la organización y a los que ya pertenecen al grupo, así que no se contabilizan en este total.
curl -X POST https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy/members/bulk-add \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userIds": ["user_abc123", "user_def456"]  }'

Respuesta:

{  "addedCount": 2}

Eliminar miembros de un grupo de la organización

POST/organizations/groups/:groupId/members/bulk-remove

Elimina miembros de un grupo de la organización manual.

Parámetros

groupId string Obligatorio

ID del grupo de la organización con el prefijo g_.

Cuerpo de la solicitud

userIds string[] Obligatorio

Array de IDs públicos de usuario con el prefijo user_. Una sola solicitud puede incluir hasta 100 usuarios.

Campos de la respuesta

removedCount number

Número de membresías que ha eliminado esta solicitud. Cursor ignora a los usuarios que no pertenecen al grupo, así que no se contabilizan en este total.
curl -X POST https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy/members/bulk-remove \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userIds": ["user_def456"]  }'

Respuesta:

{  "removedCount": 1}

Registros de auditoría

El feed de auditoría de la organización devuelve los mismos eventos que el endpoint de equipo GET /teams/audit-logs para todos los equipos vinculados a la organización, además de los eventos a nivel de organización que no están asociados a ningún equipo. Los tipos de evento y los campos de event_data se detallan en Cumplimiento y monitorización.

Obtener registros de auditoría

GET/organizations/audit-logs

Obtén los eventos del registro de auditoría de la organización asociada a tu clave de API. Pasa teamId para limitar los resultados a un solo equipo vinculado. Los parámetros de consulta, los valores predeterminados y la estructura de la respuesta son los mismos que en el endpoint de equipo, con un único añadido: cada evento incluye team_id.

Parámetros de consulta

startTime cadena | number

Hora de inicio (valor predeterminado: hace 7 días). Admite los mismos formatos de fecha que el endpoint de equipos.

endTime cadena | number

Hora de fin (valor predeterminado: now).

eventTypes cadena

Valores de event_type separados por comas por los que filtrar.

search cadena

Busca coincidencias de subcadena en user_email, event_type y event_id, sin distinguir entre mayúsculas y minúsculas. No busca en event_data.

users cadena

Direcciones de correo electrónico, IDs de usuario numéricos o IDs públicos user_, separados por comas. Hasta 100 valores. Todos los usuarios deben ser miembros de la organización.

teamId number

Limita el registro a un solo equipo. El equipo debe estar vinculado a la organización; de lo contrario, la solicitud devuelve un 403.

page number

Número de página (indexado desde 1). Predeterminado: 1

pageSize number

Resultados por página (1-500). Predeterminado: 100

Campos de respuesta

events array

Eventos de auditoría, cada uno de los cuales contiene:
  • event_id cadena - UUID del evento
  • timestamp cadena - marca de tiempo ISO 8601
  • team_id cadena - Equipo al que pertenece el evento. Vacío en los eventos a nivel de organización, como organization_group y xai_credit_transfer
  • ip_address cadena - IP del cliente que realizó la solicitud
  • user_email cadena - Actor. Consulta el formato de registro para ver los valores Api Key:, Bot: y System
  • event_type cadena - Tipo de evento
  • application_type cadena - cursor, grok_bot o vacío si se desconoce
  • event_data objeto - Campos específicos del evento. old_value y new_value se analizan como JSON cuando el valor almacenado es JSON válido

pagination objeto

Metadatos de paginación: page, pageSize, totalCount, totalPages, hasNextPage y hasPreviousPage.

params objeto

Eco de la consulta resuelta: organizationId, teamId, startDate, endDate, eventTypes, search y users.
curl -X GET "https://api.cursor.com/organizations/audit-logs?startTime=7d&endTime=now&eventTypes=organization_group,add_user" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "events": [    {      "event_id": "c2d4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",      "timestamp": "2026-09-14T09:02:11.000Z",      "team_id": "",      "ip_address": "203.0.113.42",      "user_email": "admin@company.com",      "event_type": "organization_group",      "application_type": "cursor",      "event_data": {        "action": "create",        "organization_group_id": "grp_7Hq2mKp9vRt4xLw1",        "organization_group_name": "Platform Engineering"      }    },    {      "event_id": "8a1f0f0e-0d1b-4c7e-9b3a-2f6e1c9d4a55",      "timestamp": "2026-09-14T18:30:45.123Z",      "team_id": "12345",      "ip_address": "203.0.113.42",      "user_email": "alice@company.com",      "event_type": "add_user",      "application_type": "cursor",      "event_data": {        "user_email": "bob@company.com",        "role": "member",        "source": "domain_join",        "team_id": "12345",        "invited_by_email": "",        "invited_by_user_id": "0",        "invite_id": ""      }    }  ],  "pagination": {    "page": 1,    "pageSize": 100,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  },  "params": {    "organizationId": "org_abc123",    "startDate": 1757232131000,    "endDate": 1757836931000,    "eventTypes": "organization_group,add_user"  }}

Computadoras del Bot de Grok

Recrea, termina o elimina las computadoras alojadas que ejecutan el Bot de Grok para los miembros de un equipo y, luego, haz seguimiento de la operación hasta que cada miembro tenga un resultado. Estas rutas ejecutan las mismas operaciones que Computadoras del Bot de Grok en el panel de control. Consulta Gestionar computadoras del Bot de Grok para saber qué efecto tiene cada acción en la computadora de un miembro y qué ve el miembro.

Las rutas de operación comparten estas respuestas de error:

EstadoCuándo
400Cuerpo o consulta con formato incorrecto, un campo desconocido en el cuerpo, un userId que no es miembro actual del equipo o demasiados miembros
401Clave de API no válida o la clave no tiene el scope admin:*
403Las operaciones de computadoras del Bot de Grok no están activadas para el equipo
404El equipo no está vinculado a tu organización, o la operación no existe o ya no está disponible
409Hay otra operación en curso para el equipo (solo al iniciar)
429Se superó el límite de uso. La respuesta incluye un encabezado Retry-After: 60
503Las operaciones no están disponibles temporalmente. Vuelve a intentar la misma solicitud

Iniciar operación de la computadora del Bot de Grok

POST/organizations/teams/:teamId/grok-bot/operations

Inicia una recreación, terminación o eliminación para los miembros de un equipo. La solicitud devuelve 202 Accepted en cuanto la operación queda en cola y, a partir de ahí, Cursor procesa a los miembros por lotes. Consulta periódicamente Obtener operación de la computadora del Bot de Grok para seguir el progreso.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.

Cuerpo de solicitud

action cadena Obligatorio

Qué hacer con la computadora de cada miembro:
  • recreate_vm - Crea una computadora de reemplazo con la imagen más reciente y ejecuta la configuración del equipo. Los Bots, archivos e inicios de sesión se conservan, y si un Bot está a mitad de una interacción, se pausa y se reanuda en la nueva computadora.
  • terminate_vm - Elimina la computadora actual del miembro y conserva el disco durable. El siguiente mensaje del miembro inicia una computadora nueva.
  • delete_vm_and_data - Elimina la computadora y sus datos durables, de modo que el miembro empieza desde cero. Esta acción no se puede deshacer.

userIds number[] Obligatorio

IDs de usuario numéricos de los miembros a los que se aplicará el cambio. Para obtenerlos, llama a Listar miembros de la organización con teamId. Envía entre 1 y 25.000 IDs, o como máximo 1.000 para delete_vm_and_data. Los duplicados se ignoran. Cada ID debe pertenecer a un miembro actual del equipo que haya iniciado sesión en Cursor; si alguno no cumple este requisito, la solicitud devuelve 400 y no se inicia nada. Los miembros sin computadora se omiten en la recreación y la terminación. Aun así, delete_vm_and_data elimina sus datos durables.

operationId cadena Obligatorio

Un UUID que generas para esta operación. Si una solicitud agota el tiempo de espera o falla, vuelve a enviarla con el mismo operationId. Cursor devuelve 202 para la operación existente en lugar de iniciar una segunda, incluso si esa operación sigue en ejecución. Cursor no compara el resto del cuerpo en los reintentos, así que genera un UUID nuevo para cada operación nueva.

Campos de respuesta

Devuelve 202 Accepted con:

Si ya hay otra operación en ejecución para el equipo, la ruta devuelve 409 con code: "conflict", un message y runningOperationId, el ID de la operación en curso. runningOperationId es null cuando Cursor no puede identificarla; en ese caso, llama a Obtener la última operación de la computadora del Bot de Grok.

curl -X POST https://api.cursor.com/organizations/teams/7/grok-bot/operations \  -u YOUR_ORGANIZATION_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "action": "recreate_vm",    "userIds": [12345, 12346, 12347],    "operationId": "3f2a9c1e-8b4d-4e6f-a1c2-5d7e9f0b1a2c"  }'

Respuesta:

{  "operationId": "3f2a9c1e-8b4d-4e6f-a1c2-5d7e9f0b1a2c"}

Respuestas de error:

409: ya hay otra operación en curso para el equipo:

{  "code": "conflict",  "message": "Another Grok Bot computer operation is already running for this team. Wait for it to finish, then try again.",  "runningOperationId": "b81c4e27-6a90-4f3d-9e15-2c8d7a4f6b03"}

400: un usuario ya no es miembro del equipo:

{  "code": "error",  "message": "Every userId must be a current member of the team."}

403: las operaciones no están activadas para el equipo:

{  "code": "error",  "message": "Bot fleet admin API access is not enabled for this team"}

Obtener operación de la computadora del Bot de Grok

GET/organizations/teams/:teamId/grok-bot/operations/:operationId

Obtiene el progreso de una operación: recuentos agregados de todos los miembros y una página de resultados por miembro. Consulta esta ruta periódicamente hasta que state deje de ser running.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.

operationId cadena Obligatorio

El UUID enviado a Iniciar operación de la computadora del Bot de Grok.

Parámetros de consulta

limit number

Resultados por página para cada miembro (1-1000). Valor predeterminado: 100

cursor cadena

El valor nextCursor de la página anterior. Omítelo en la primera página.

Campos de respuesta

operationId cadena

El ID de la operación.

action cadena

recreate_vm, terminate_vm o delete_vm_and_data.

state cadena

running hasta que todos los miembros tengan un resultado. Una operación finalizada queda en succeeded si ningún miembro falló, en partially_succeeded si algunos miembros fallaron y los demás se completaron correctamente o se omitieron, y en failed si fallaron todos los miembros.

counts objeto

Recuento de miembros de toda la operación: total, queued, running, succeeded, skipped y failed. noVmSkipped es la parte de skipped que corresponde a miembros que no tenían computadora. Siempre vale 0 para delete_vm_and_data, que elimina los datos durables haya o no una computadora en ejecución.

items array | null

Resultados por miembro de esta página. Cada uno incluye:
  • userId number - ID numérico de usuario del miembro
  • state cadena - queued, running, succeeded, skipped o failed
  • reason string | null - Motivo por el que se omitió al miembro o por el que falló la operación. null en caso contrario
items es null en las operaciones de más de 1000 miembros. Estas solo devuelven counts.

itemsTruncated boolean

true cuando la operación tiene más de 1000 miembros y no se conservan los resultados de cada miembro.

nextCursor cadena | null

Pásalo como cursor para obtener la siguiente página de items. Es null en la última página.

Los valores de reason que verás con más frecuencia:

reasonstateSignificado
no-boxskippedEl miembro no tenía ninguna computadora activa ni en hibernación. Solo para Recrear y Terminar
team-member-not-foundskippedEl miembro abandonó el equipo mientras la operación estaba en cola
member-identity-changedskippedLa cuenta del miembro cambió mientras la operación estaba en cola
recreate-already-in-progressfailedLa computadora del miembro ya se estaba recreando. Inicia una nueva operación para este miembro cuando termine
authorization-revokedfailedLa clave de API que inició la operación se revocó, caducó o perdió el permiso admin:* antes de que Cursor llegara a este miembro

Cualquier otro valor de reason en un miembro fallido indica que la acción no se completó. Inicia una nueva operación para esos miembros. Consulta Miembros omitidos y fallidos para saber cómo continuar.

Un 404 con Operation not found. significa que la operación nunca llegó a iniciarse o que ha caducado. Un 404 con This operation finished, and its status is no longer available. significa que la operación se completó, pero Cursor ya no conserva sus resultados.

curl -X GET "https://api.cursor.com/organizations/teams/7/grok-bot/operations/3f2a9c1e-8b4d-4e6f-a1c2-5d7e9f0b1a2c?limit=100" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "operationId": "3f2a9c1e-8b4d-4e6f-a1c2-5d7e9f0b1a2c",  "action": "recreate_vm",  "state": "partially_succeeded",  "counts": {    "total": 3,    "queued": 0,    "running": 0,    "succeeded": 1,    "skipped": 1,    "failed": 1,    "noVmSkipped": 1  },  "items": [    { "userId": 12345, "state": "succeeded", "reason": null },    { "userId": 12346, "state": "skipped", "reason": "no-box" },    { "userId": 12347, "state": "failed", "reason": "recreate-already-in-progress" }  ],  "itemsTruncated": false,  "nextCursor": null}

Obtener la última operación de la computadora del Bot de Grok

GET/organizations/teams/:teamId/grok-bot/operations/latest

Obtiene la operación en curso del equipo o, si no hay ninguna en curso, la más reciente. Úsalo para averiguar qué está bloqueando y provocando un 409, o para retomar una operación cuando ya no tienes su ID. El equipo no tiene una última operación hasta que se ejecute alguna; mientras tanto, la ruta devuelve 404.

Parámetros

teamId number Obligatorio

ID entero de un equipo vinculado a la organización.

Parámetros de consulta

Acepta los mismos parámetros limit y cursor que Obtener operación de la computadora del Bot de Grok.

Campos de respuesta

Los mismos campos que Obtener operación de la computadora del Bot de Grok.

curl -X GET https://api.cursor.com/organizations/teams/7/grok-bot/operations/latest \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "operationId": "b81c4e27-6a90-4f3d-9e15-2c8d7a4f6b03",  "action": "terminate_vm",  "state": "running",  "counts": {    "total": 2400,    "queued": 2340,    "running": 20,    "succeeded": 38,    "skipped": 2,    "failed": 0,    "noVmSkipped": 2  },  "items": null,  "itemsTruncated": true,  "nextCursor": null}