Обзор API Cursor

Cursor предоставляет несколько API для программного доступа к данным вашей команды, ИИ-агентам для разработки кода и аналитике.

Доступные API

API облачных агентов и SDK запускают рабочие процессы агентов Cursor (контекст рабочего пространства, инструменты, команды и правки). Это не самостоятельный API для инференса моделей или чат-завершений. Cursor Router выбирает модели для этих запусков агентов при использовании Auto / auto-smart; см. Router в TypeScript SDK или Python SDK.

Аутентификация

Все API Cursor поддерживают базовую аутентификацию. API облачных агентов также поддерживает Bearer-токены — используйте вариант, который удобнее для вашего HTTP-клиента.

Базовая аутентификация

Используйте API-ключ в качестве имени пользователя при ��азовой аутентификации, оставив пароль пустым:

curl https://api.cursor.com/teams/members \  -u YOUR_API_KEY:

Или укажите заголовок Authorization напрямую:

Authorization: Basic {base64_encode('YOUR_API_KEY:')}

Аутентификация по Bearer-токену (API облачных агентов)

API облачных агентов также поддерживает заголовок Authorization: Bearer <key>. Обе схемы работают одинаково — используйте ту, которую проще поддерживает ваш HTTP-клиент:

curl https://api.cursor.com/v1/me \  -H "Authorization: Bearer YOUR_API_KEY"

Создание API-ключей

Администраторы команды могут создавать API-ключи и управлять ими на странице API-ключей в дашборде.

Admin API и API отслеживания ИИ-кода

1. Перейдите в cursor.com/dashboard → API-ключ
2. Нажмите New API Key
3. Укажите понятное имя ключа (например, «Интеграция с дашбордом использования»)
4. Сразу скопируйте созданный ключ: повторно он не будет показан

Формат ключа: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Требуемая область действия: admin:*

API аналитики

Создайте API-ключ в дашборде Cursor → API-ключи.

API облачных агентов

Создайте пользовательский API-ключ в Cursor дашборд → API-ключ или используйте API-ключ сервисного аккаунта из настроек команды.

Ограничения частоты запросов

Во всех API действует ограничение частоты запросов, обеспечивающее справедливое использование и стабильность системы. Ограничения устанавливаются для каждой команды и сбрасываются каждую минуту.

Ограничения частоты запросов для API

Ответ при превышении лимита запросов

При превышении лимита запросов вы получите ответ 429 Too Many Requests:

{  "error": "Too Many Requests",  "message": "Rate limit exceeded. Please try again later."}

Кэширование

Некоторые API поддерживают HTTP-кэширование с ETag, что позволяет снизить потребление трафика и повысить производительность.

Поддерживаемые API

• Analytics API: Все конечные точки (как для команды, так и для отдельных пользователей) поддерживают HTTP-кеширование
• API отслеживания ИИ-кода: Конечные точки поддерживают HTTP-кеширование

Как работает кэширование

1. Первый запрос: Отправьте запрос к любой поддерживаемой конечной точке
2. Ответ содержит ETag: API возвращает в ответе заголовок ETag
3. Последующие запросы: Добавляйте значение ETag в заголовок If-None-Match
4. 304 Not Modified: Если данные не изменились, вы получите ответ 304 Not Modified без тела

Пример

# Первый запросcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# Ответ содержит: ETag: "abc123xyz"# Следующий запрос с ETagcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# Возвращает 304 Not Modified, если данные не изменились

Время кэширования

• Время кэширования: 15 минут (Cache-Control: public, max-age=900)
• Ответы содержат заголовок ETag
• Добавляйте заголовок If-None-Match в последующие запросы, чтобы получать ответ 304 Not Modified, если данные не изменились

Преимущества

• Снижает потребление трафика: ответы 304 не содержат тела
• Ускоряет ответы: не требует обработки неизменившихся данных
• Не расходует ограничение частоты запросов: ответы 304 не учитываются в ограничении частоты запросов
• Повышает производительность: особенно полезно для конечных точек с частым опросом

Рекомендации

1. Реализуйте стратегию экспоненциальной задержки

При получении ответа 429 повторяйте попытку с увеличивающейся задержкой:

import timeimport requestsdef make_request_with_backoff(url, headers, max_retries=5):    for attempt in range(max_retries):        response = requests.get(url, headers=headers)                if response.status_code == 429:            # Экспоненциальная задержка: 1 с, 2 с, 4 с, 8 с, 16 с            wait_time = 2 ** attempt            print(f"Rate limited. Waiting {wait_time}s before retry...")            time.sleep(wait_time)            continue                    return response        raise Exception("Max retries exceeded")

2. Равномерно распределяйте запросы во времени

Распределяйте API-вызовы во времени, избегая всплесков нагрузки:

• Планируйте запуск пакетных задач с разными интервалами
• Добавляйте задержки между запросами при обработке больших наборов данных
• Используйте системы очередей, чтобы сглаживать всплески трафика

3. Используйте кэширование

Для Analytics API и API отслеживания ИИ-кода:

Эти API поддерживают HTTP-кэширование с ETag. Подробнее об использовании ETag для снижения объёма передаваемых данных и предотвращения ненужных запросов см. в разделе Кэширование выше.

Основные преимущества:

• Снижение объёма передаваемых данных
• Более быстрые ответы, если данные не изменились
• Не учитывается при ограничении частоты запросов (для ответов 304)

Используйте сокращения дат (7d, 30d) вместо временных меток для более эффективного кэширования в Analytics API.

4. Отслеживайте использование

Следите за характером запросов, чтобы не превышать лимиты:

• Записывайте временные метки вызовов API и коды ответов
• Настройте оповещения для ответов с кодом 429
• Отслеживайте ежедневные и еженедельные тенденции использования
• Настраивайте интервалы опроса в соответствии с реальными потребностями

5. Эффективно используйте пакетную обработку

Для конечных точек с пагинацией:

• Выбирайте подходящий размер страницы, чтобы получать больше данных за один запрос
• Для конечных точек Analytics API by-user: используйте параметр users, чтобы отфильтровать нужных пользователей
• Для извлечения больших объёмов данных: используйте конечные точки CSV, если они доступны (они эффективно передают данные в потоке)

6. Опрос с оптимальной периодичностью

Не опрашивайте слишком часто редко обновляемые конечные точки:

• Admin API /teams/daily-usage-data: не чаще одного раза в час (данные агрегируются ежечасно)
• Admin API /teams/filtered-usage-events: не чаще одного раза в час (данные агрегируются ежечасно)
• Admin API /organizations/pooled-usage: не чаще одного раза в час (данные агрегируются ежечасно)
• Admin API /organizations/filtered-usage-events: не чаще одного раза в час (данные агрегируются ежечасно)
• Analytics API: используйте сокращения дат (7d, 30d) для более эффективного кэширования
• API отслеживания ИИ-кода: данные поступают практически в реальном времени, но достаточно опрашивать их раз в несколько минут

7. Обрабатывайте ошибки корректно

Реализуйте обработку ошибок для всех вызовов API:

async function fetchAnalytics(endpoint) {  try {    const response = await fetch(`https://api.cursor.com${endpoint}`, {      headers: {        'Authorization': `Basic ${btoa(API_KEY + ':')}`      }    });        if (response.status === 429) {      // Превышен лимит запросов — реализуйте экспоненциальную задержку      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Недопустимый API-ключ      throw new Error('Authentication failed');    }        if (response.status === 403) {      // Недостаточно прав доступа      throw new Error('Enterprise access required');    }        if (!response.ok) {      throw new Error(`API error: ${response.status}`);    }        return await response.json();  } catch (error) {    console.error('API request failed:', error);    throw error;  }}

Распространённые ответы при ошибках

Во всех API используются стандартные коды состояния HTTP:

400 Неверный запрос

Параметры запроса недопустимы или отсутствуют обязательные поля.

{  "error": "Bad Request",  "message": "Some users are not in the team"}

401 Не авторизован

Недопустимый или отсутствующий API-ключ.

{  "error": "Unauthorized",  "message": "Invalid API key"}

403 Доступ запрещён

API-ключ действителен, но недостаточно прав доступа (например, для использования функций Enterprise на тарифе, отличном от Enterprise).

{  "error": "Forbidden",  "message": "Enterprise access required"}

404 Не найдено

Запрошенный ресурс не найден.

{  "error": "Not Found",  "message": "Resource not found"}

429 Слишком много запросов

Превышен лимит запросов. Используйте экспоненциальную задержку между повторными попытками.

{  "error": "Too Many Requests",  "message": "Rate limit exceeded. Please try again later."}

500 Внутренняя ошибка сервера

Ошибка на стороне сервера. Если ошибка сохраняется, обратитесь в службу поддержки.

{  "error": "Internal Server Error",  "message": "An unexpected error occurred"}