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 y consultar o actualizar el acceso a modelos. 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 básica 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 a nivel de equipo 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.
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.

Alcance	Acceso	Rutas de ejemplo
`members:read`	Acceso 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:read`	Acceso 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
`admin:*`	Acceso completo a todas las rutas de la organización.	Todo lo anterior

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.

Disponibilidad: Solo para Enterprise
Autenticación: clave de API de organización (Basic auth). Leer miembros acepta el alcance de solo lectura members:read; mover miembros requiere members:*. Las claves con admin:* funcionan para ambos casos.
Alcance: GET /organizations/members es de ámbito organizacional, está paginado y devuelve el rol de organización de cada miembro, además de sus asignaciones a todos los equipos vinculados, en una sola respuesta.
Paginación: GET /organizations/members acepta page y pageSize. pageSize tiene un límite de 200; los valores mayores se reducen a 200.

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.

Campos de la respuesta

members array

Array de objetos de miembro de la organización, cada uno con lo siguiente:

userId number - Identificador numérico único 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": [    {      "userId": 12345,      "email": "developer@company.com",      "name": "Alex",      "organizationRole": "member",      "teams": [        { "teamId": 7, "teamRole": "member" },        { "teamId": 8, "teamRole": "owner" }      ]    },    {      "userId": 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".

Disponibilidad: Solo Enterprise
Autenticación: clave de API de la organización (Basic auth). La clave debe incluir el scope members:* para esta ruta; las claves con admin:* también funcionan porque admin incluye members.
Coincidencia de organización: El organizationId del body debe corresponder a la misma organización que la clave de API; de lo contrario, la solicitud se rechaza.
Conjunto de equipos: teamIds es el conjunto exacto de equipos a los que debe pertenecer el usuario después de la llamada. Se eliminará al usuario de cualquier equipo que NO figure en la lista, así que incluye en el conjunto los equipos actuales del usuario si quieres conservarlos.
Un campo de equipo por entrada: Proporciona exactamente uno de teamIds o destinationTeamId para cada entrada.
Límite de equipos por entrada: Los teamIds de una entrada pueden incluir como máximo 100 equipos.
El usuario de destino ya debe ser miembro de la organización para que la sincronización se complete correctamente.
Todos los equipos de la entrada deben estar vinculados a la organización para que la sincronización se complete correctamente.
Si una entrada de users falla, las demás aún pueden completarse correctamente; comprueba el status y el errorMessage de cada entrada de results.
Tamaño del lote: Una sola solicitud puede incluir hasta 500 entradas. Si hace falta, envía lotes adicionales en solicitudes separadas.

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.

Disponibilidad: Solo para Enterprise
Autenticación: clave de API de organización (Basic auth). La clave debe incluir el alcance usage:* para estas rutas; las claves con admin:* también funcionan porque admin incluye usage.
Coincidencia de organización: El organizationId en el cuerpo debe corresponder a la misma organización que la clave de API; de lo contrario, la solicitud se rechaza.
Pertenencia del equipo: Cada entrada en teamIds debe pertenecer a la organización. Las solicitudes que hacen referencia a un equipo fuera de la organización se rechazan.
Consulta periódica: Los datos de consumo se agregan por hora. Consulta estos endpoints como máximo una vez por hora. Con límite de 20 solicitudes por minuto. Consulta los límites de uso y mejores prácticas.

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.

Por defecto, se devuelven eventos de todos los equipos del pool de la organización. Envía teamIds para limitar la respuesta a equipos específicos.

Cálculo de costes: Suma el campo chargedCents de todos los eventos para hacer coincidir los costes a nivel de evento con el desglose por equipo de usedCents de /organizations/pooled-usage. Este campo incluye tanto el coste del modelo como la tasa de tokens de Cursor cuando una solicitud cumple los requisitos para esa tasa.

El campo cursorTokenFee representa la tasa de tokens de Cursor y solo aparece cuando la tasa se aplica a una solicitud a un modelo de terceros. Esto incluye los casos en los que Auto dirige una solicitud a un modelo de terceros. Los modelos propios de Cursor como Grok y Composer, y las cuentas enterprise basadas en solicitudes no incluyen esta tarifa. Consulta tasa de tokens de Cursor.

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.

El intervalo de fechas no puede superar los 30 días. Realiza varias solicitudes para períodos más largos.

Los campos subscriptionIncludedReqs, usageBasedReqs y apiKeyReqs cuentan eventos de uso en bruto, no unidades de solicitud facturables de modelos anteriores de precios basados en solicitudes.

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

El gasto se informa para los equipos agrupados de la organización, por lo que no se incluyen los campos de un solo equipo subscriptionCycleStart, overallSpendCents, fastPremiumRequests, hardLimitOverrideDollars y monthlyLimitDollars de /teams/spend. La ventana del informe se devuelve en period.

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

Las rutas de acceso a modelos están en vista previa y pueden cambiar. Las rutas, los campos de respuesta y el comportamiento de los errores pueden modificarse antes de su disponibilidad general.

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.

Disponibilidad: Organizaciones Enterprise. Los equipos de destino deben tener activado el control de acceso a modelos.
Autenticación: Clave de API de organización (Basic auth). Las lecturas requieren models:read. Las escrituras requieren models:*. Las claves con admin:* funcionan para ambas. Las claves members:*, usage:* y read:* no pueden llamar a estas rutas.
Pertenencia a la organización: Cada teamId debe estar vinculado a la organización. En las rutas de un solo equipo, los equipos desconocidos o no vinculados devuelven 404. En las rutas masivas, los equipos no vinculados se devuelven como filas de error HTTP 200.
Primero la configuración: Las lecturas y escrituras de proveedores y modelos devuelven 409 mientras el equipo siga siendo unrestricted (o legacy). Primero crea una política personalizada con PUT /organizations/teams/{teamId}/model-access/configuration (o la ruta de configuración masiva). El primer PUT de valores predeterminados establece los valores predeterminados del catálogo; no clona el mapa de activación y desactivación de otro equipo.
Volver a acceso sin restricciones: Envía { "state": "unrestricted" } en el PUT de configuración de cada equipo o masivo.
Éxito parcial masivo: Las rutas masivas aceptan hasta 100 teamIds y siempre devuelven HTTP 200 cuando se procesa el lote, incluso si algunas filas fallan. Revisa errorCount y cada results[].status. Las filas correctas no se revierten. Las operaciones son idempotentes por equipo, así que vuelve a intentar solo los teamId que fallaron. Una respuesta 4xx o 5xx rechaza toda la solicitud y no aplica cambios. La estructura de la respuesta corresponde a /organizations/team-memberships/sync.
Límites de uso: 20 solicitudes por minuto. Las escrituras aparecen en los registros de auditoría del equipo como eventos team_settings. Consulta los límites de uso y las mejores prácticas.

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": "…" }

Estado	Cuándo
`401`	Clave incorrecta o falta `models:read` / `models:` (o `admin:`)
`403`	El control de acceso a modelos no está disponible para ese equipo (rutas de un solo equipo)
`404`	El equipo no está vinculado a la organización (rutas de un solo equipo)
`409`	Lectura de un proveedor o modelo, o escritura de un solo equipo mientras el `state` de ese equipo sea `unrestricted` o `legacy`
`400`	ID 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 agrupan a los miembros de los equipos vinculados a la misma organización. Para la configuración del panel de control y los controles a nivel de grupo, consulta Grupos de la organización.

Autenticación: clave de API de organización (Basic auth). Las rutas de lectura requieren el alcance members:*. Las rutas de escritura también requieren members:*. Las claves con admin:* también funcionan porque admin implica members.
ID de grupo: Los ID de grupo de la organización usan el prefijo g_.
Paginación: Las rutas de lista aceptan page y pageSize. Ambos valores deben ser enteros positivos.

Listar grupos de la organización

GET/organizations/groups

Obtén los grupos de la organización asociada a tu clave de API.

Parámetros de consulta

page number

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

pageSize number

Número de grupos por página.

curl -X GET "https://api.cursor.com/organizations/groups?page=1&pageSize=50" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "groups": [    {      "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Engineering",      "createdAt": "2026-01-15T10:30:00.000Z",      "updatedAt": "2026-01-20T14:22:00.000Z"    },    {      "id": "g_kljUvI0ASZORvSEXf9hV0ydcso",      "name": "Design",      "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  }}

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_.

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

Respuesta:

{  "group": {    "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Engineering",    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-20T14:22:00.000Z"  }}

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 la primera página.

pageSize number

Número de miembros por página.

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.

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 ID de usuario públicos con el prefijo user_. Una sola solicitud puede incluir hasta 100 usuarios.

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.

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 de usuario públicos con el prefijo user_. Una sola solicitud puede incluir hasta 100 usuarios.

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}

API de organización

La API de organización usa Autenticación básica 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 a nivel de equipo 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.
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

Alcance	Acceso	Rutas de ejemplo
`members:read`	Acceso 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:read`	Acceso 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
`admin:*`	Acceso completo a todas las rutas de la organización.	Todo lo anterior

¿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.

Disponibilidad: Solo para Enterprise
Autenticación: clave de API de organización (Basic auth). Leer miembros acepta el alcance de solo lectura members:read; mover miembros requiere members:*. Las claves con admin:* funcionan para ambos casos.
Alcance: GET /organizations/members es de ámbito organizacional, está paginado y devuelve el rol de organización de cada miembro, además de sus asignaciones a todos los equipos vinculados, en una sola respuesta.
Paginación: GET /organizations/members acepta page y pageSize. pageSize tiene un límite de 200; los valores mayores se reducen a 200.

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.

Campos de la respuesta

members array

Array de objetos de miembro de la organización, cada uno con lo siguiente:

userId number - Identificador numérico único 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": [    {      "userId": 12345,      "email": "developer@company.com",      "name": "Alex",      "organizationRole": "member",      "teams": [        { "teamId": 7, "teamRole": "member" },        { "teamId": 8, "teamRole": "owner" }      ]    },    {      "userId": 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

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

successCount number

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

errorCount number

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

Disponibilidad: Solo Enterprise
Autenticación: clave de API de la organización (Basic auth). La clave debe incluir el scope members:* para esta ruta; las claves con admin:* también funcionan porque admin incluye members.
Coincidencia de organización: El organizationId del body debe corresponder a la misma organización que la clave de API; de lo contrario, la solicitud se rechaza.
Conjunto de equipos: teamIds es el conjunto exacto de equipos a los que debe pertenecer el usuario después de la llamada. Se eliminará al usuario de cualquier equipo que NO figure en la lista, así que incluye en el conjunto los equipos actuales del usuario si quieres conservarlos.
Un campo de equipo por entrada: Proporciona exactamente uno de teamIds o destinationTeamId para cada entrada.
Límite de equipos por entrada: Los teamIds de una entrada pueden incluir como máximo 100 equipos.
El usuario de destino ya debe ser miembro de la organización para que la sincronización se complete correctamente.
Todos los equipos de la entrada deben estar vinculados a la organización para que la sincronización se complete correctamente.
Si una entrada de users falla, las demás aún pueden completarse correctamente; comprueba el status y el errorMessage de cada entrada de results.
Tamaño del lote: Una sola solicitud puede incluir hasta 500 entradas. Si hace falta, envía lotes adicionales en solicitudes separadas.

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 }    ]  }'

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"}

{  "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

Disponibilidad: Solo para Enterprise
Autenticación: clave de API de organización (Basic auth). La clave debe incluir el alcance usage:* para estas rutas; las claves con admin:* también funcionan porque admin incluye usage.
Coincidencia de organización: El organizationId en el cuerpo debe corresponder a la misma organización que la clave de API; de lo contrario, la solicitud se rechaza.
Pertenencia del equipo: Cada entrada en teamIds debe pertenecer a la organización. Las solicitudes que hacen referencia a un equipo fuera de la organización se rechazan.
Consulta periódica: Los datos de consumo se agregan por hora. Consulta estos endpoints como máximo una vez por hora. Con límite de 20 solicitudes por minuto. Consulta los límites de uso y mejores prácticas.

Obtener uso agrupado

POST/organizations/pooled-usage

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

Por defecto, se devuelven eventos de todos los equipos del pool de la organización. Envía teamIds para limitar la respuesta a equipos específicos.

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

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.

El intervalo de fechas no puede superar los 30 días. Realiza varias solicitudes para períodos más largos.

Los campos subscriptionIncludedReqs, usageBasedReqs y apiKeyReqs cuentan eventos de uso en bruto, no unidades de solicitud facturables de modelos anteriores de precios basados en solicitudes.

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

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

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

Las rutas de acceso a modelos están en vista previa y pueden cambiar. Las rutas, los campos de respuesta y el comportamiento de los errores pueden modificarse antes de su disponibilidad general.

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

Disponibilidad: Organizaciones Enterprise. Los equipos de destino deben tener activado el control de acceso a modelos.
Autenticación: Clave de API de organización (Basic auth). Las lecturas requieren models:read. Las escrituras requieren models:*. Las claves con admin:* funcionan para ambas. Las claves members:*, usage:* y read:* no pueden llamar a estas rutas.
Pertenencia a la organización: Cada teamId debe estar vinculado a la organización. En las rutas de un solo equipo, los equipos desconocidos o no vinculados devuelven 404. En las rutas masivas, los equipos no vinculados se devuelven como filas de error HTTP 200.
Primero la configuración: Las lecturas y escrituras de proveedores y modelos devuelven 409 mientras el equipo siga siendo unrestricted (o legacy). Primero crea una política personalizada con PUT /organizations/teams/{teamId}/model-access/configuration (o la ruta de configuración masiva). El primer PUT de valores predeterminados establece los valores predeterminados del catálogo; no clona el mapa de activación y desactivación de otro equipo.
Volver a acceso sin restricciones: Envía { "state": "unrestricted" } en el PUT de configuración de cada equipo o masivo.
Éxito parcial masivo: Las rutas masivas aceptan hasta 100 teamIds y siempre devuelven HTTP 200 cuando se procesa el lote, incluso si algunas filas fallan. Revisa errorCount y cada results[].status. Las filas correctas no se revierten. Las operaciones son idempotentes por equipo, así que vuelve a intentar solo los teamId que fallaron. Una respuesta 4xx o 5xx rechaza toda la solicitud y no aplica cambios. La estructura de la respuesta corresponde a /organizations/team-memberships/sync.
L��mites de uso: 20 solicitudes por minuto. Las escrituras aparecen en los registros de auditoría del equipo como eventos team_settings. Consulta los límites de uso y las mejores prácticas.

Listar la configuración de acceso a modelos

GET/organizations/teams/model-access/configuration

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.

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

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

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

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.

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}

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.

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": "…" }

Estado	Cuándo
`401`	Clave incorrecta o falta `models:read` / `models:` (o `admin:`)
`403`	El control de acceso a modelos no está disponible para ese equipo (rutas de un solo equipo)
`404`	El equipo no está vinculado a la organización (rutas de un solo equipo)
`409`	Lectura de un proveedor o modelo, o escritura de un solo equipo mientras el `state` de ese equipo sea `unrestricted` o `legacy`
`400`	ID 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

Grupos de la organización

Autenticación: clave de API de organización (Basic auth). Las rutas de lectura requieren el alcance members:*. Las rutas de escritura también requieren members:*. Las claves con admin:* también funcionan porque admin implica members.
ID de grupo: Los ID de grupo de la organización usan el prefijo g_.
Paginación: Las rutas de lista aceptan page y pageSize. Ambos valores deben ser enteros positivos.

Listar grupos de la organización

GET/organizations/groups

Obtén los grupos de la organización asociada a tu clave de API.

Parámetros de consulta

page number

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

pageSize number

Número de grupos por página.

curl -X GET "https://api.cursor.com/organizations/groups?page=1&pageSize=50" \  -u YOUR_ORGANIZATION_API_KEY:

Respuesta:

{  "groups": [    {      "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Engineering",      "createdAt": "2026-01-15T10:30:00.000Z",      "updatedAt": "2026-01-20T14:22:00.000Z"    },    {      "id": "g_kljUvI0ASZORvSEXf9hV0ydcso",      "name": "Design",      "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  }}

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_.

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

Respuesta:

{  "group": {    "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Engineering",    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-20T14:22:00.000Z"  }}

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 la primera página.

pageSize number

Número de miembros por página.

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  }}

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}

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}

Command Palette

Descripción general de la API

API de agentes de programación en la nube

API de administración

API de Análisis

API de seguimiento de código con IA

API de origen

API de organización

Command Palette

Descripción general de la API

API de agentes de programación en la nube

API de administración

API de Análisis

API de seguimiento de código con IA

API de origen

API de organización