Cursor API の概要

Cursor では、チームのデータ、AI 搭載コーディングエージェント、利用分析にプログラムからアクセスできる複数の API を提供しています。

利用可能な API

Cloud Agents API と SDK は、Cursor エージェントのワークフロー (ワークスペースコンテキスト、ツール、コマンド、編集) を実行します。これらは、スタンドアロンのモデル推論 API やチャット補完 API ではありません。Auto / auto-smart を使用すると、Cursor Router がこれらのエージェント実行に使用するモデルを選択します。詳しくは、TypeScript SDK の Router または Python SDK を参照してください。

認証

すべての Cursor API でベーシック認証を利用できます。Cloud Agents API では Bearer トークンも利用できるため、HTTP クライアントで扱いやすい方を選択してください。

ベーシック認証

ベーシック認証では、API キーをユーザー名として使用し、パスワードは空欄のままにします。

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

または、Authorization ヘッダーを直接設定します。

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

Bearer 認証 (Cloud Agents API)

Cloud Agents API では、Authorization: Bearer <key> ヘッダーも使用できます。どちらの方式も同じように動作するため、HTTP クライアントで使いやすい方を使用してください。

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

API キーの作成

チーム管理者は、ダッシュボードの API キーページで API キーを作成・管理できます。

Admin API & AI Code Tracking API

1. cursor.com/dashboard → API キー を開きます
2. New API Key をクリックします
3. キーにわかりやすい名前を付けます (例: 「Usage Dashboard Integration」)
4. 生成されたキーをすぐにコピーします。後で再表示することはできません

キーの形式: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

必要なスコープ: admin:*

利用分析 API

Cursor Dashboard → API キーから API キーを作成します。

Cloud Agents API

Cursor Dashboard → API キー でユーザー API キーを作成するか、チーム設定でサービスアカウントの API キーを使用します。

レート制限

すべての API では、公平な利用とシステムの安定性を確保するためにレート制限を設けています。レート制限はチームごとに適用され、毎分リセットされます。

API 別のレート制限

レート制限超過時のレスポンス

レート制限を超過すると、429 Too Many Requests レスポンスが返されます。

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

キャッシュ

複数の API で、ETag を利用した HTTP キャッシュにより、帯域幅の使用量を削減し、パフォーマンスを向上できます。

HTTP キャッシュ対応 API

• 利用分析 API: チーム単位・ユーザー単位を問わず、すべてのエンドポイントで HTTP キャッシュを利用できます
• AI Code Tracking 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"# ETag を含む後続のリクエストcurl -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. キャッシュを活用する

利用分析 API と AI Code Tracking API:

これらの API は、ETag を使用した HTTP キャッシュをサポートしています。ETag を使用して帯域幅の使用量を削減し、不要なリクエストを回避する方法については、上記の Caching セクションを参照してください。

主なメリット:

• 帯域幅の使用量を削減
• データが変更されていない場合、レスポンスが高速化
• 304 レスポンスはレート制限の対象外

利用分析 API でキャッシュ効果を高めるには、タイムスタンプではなく日付ショートカット (7d、30d) を使用します。

4. 利用状況を監視する

リクエストの傾向を追跡し、制限内に収めましょう。

• API 呼び出しのタイムスタンプとレスポンスコードをログに記録する
• 429 レスポンスに対するアラートを設定する
• 日次・週次の利用傾向を監視する
• 実際のニーズに応じてポーリング間隔を調整する

5. バッチ処理を適切に行う

ページネーション対応のエンドポイントの場合:

• リクエストごとにより多くのデータを取得できるよう、適切なページサイズを設定する
• 利用分析 APIのユーザー別エンドポイントの場合: users パラメータを使用して特定のユーザーに絞り込む
• 大規模なデータ抽出の場合: 利用可能であればCSVエンドポイントを使用する (データを効率的にストリーミングできる)

6. 適切な間隔でポーリングする

更新頻度の低いエンドポイントを過剰にポーリングしないでください。

• Admin API /teams/daily-usage-data: ポーリングは最大で1時間に1回 (データは1時間ごとに集計)
• Admin API /teams/filtered-usage-events: ポーリングは最大で1時間に1回 (データは1時間ごとに集計)
• Admin API /organizations/pooled-usage: ポーリングは最大で1時間に1回 (データは1時間ごとに集計)
• Admin API /organizations/filtered-usage-events: ポーリングは最大で1時間に1回 (データは1時間ごとに集計)
• 利用分析 API: キャッシュ効果を高めるため、日付ショートカット (7d、30d) を使用
• AI Code Tracking 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 Bad Request

リクエストのパラメータが無効であるか、必須フィールドが不足しています。

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

401 Unauthorized

API キーが無効か、指定されていません。

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

403 Forbidden

API キーは有効ですが、権限が不足しています (例：エンタープライズ機能はエンタープライズプランでのみ利用可能です) 。

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