Cursor API の概要

Cursor は、チームのデータや AI 搭載のコーディングエージェント、アナリティクスへプログラムからアクセスできる複数の API を提供します。

利用可能な API

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

認証

Admin、Analytics、AI Code Tracking、Bugbot の各 API は ベーシック認証を使用します。Cloud Agents API はベーシック認証または Bearer 認証をサポートしています。Origin API は Origin CLI または Origin App を通じて Bearer credentials を使用します。

ベーシック認証

ベーシック認証では、ユーザー名に自分の 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 キー をクリックします
3. キーにわかりやすい名前を付けます (例：「利用ダッシュボード連携」)
4. 生成されたキーはすぐにコピーしてください。後で再表示することはできません

キーの形式: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

必要なスコープ: admin:*

Analytics API

Cursor Dashboard → API キーで API キーを生成します。

Cloud Agents API

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

Origin API

ユーザー認証が必要なリクエストでは、Origin CLI でサインインするか、個人用の user API キーを指定してください。CLI は Origin を呼び出す前に、その key を short-lived な access token と交換します。admin:* スコープを持つ Team Admin API キーでは Origin への認証はできません。App は app JWT と installation access token を使用します。詳細は Origin API の認証を参照してください。

レート制限

公平な利用とシステムの安定性のため、すべての API にレート制限が適用されています。制限は認証済みユーザー、チーム、または組織ごとに適用され、そのほとんどは単一のエンドポイント単位で適用されます。エンドポイントに別の制限が記載されていない限り、デフォルトは 1 分あたり 20 リクエストです。

API ごとのレート制限

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

レート制限を超えると、429 Too Many Requests のレスポンスが返されます。Admin API と Organization API のレスポンスには Retry-After: 60 と次のボディが含まれます:

{  "code": "error",  "message": "Rate limit exceeded"}

キャッシュ

複数の API は、帯域幅の消費を抑えパフォーマンスを向上させるため、ETag を用いた HTTP キャッシュに対応しています。

対応API

• Analytics API: すべてのエンドポイント（チーム単位・ユーザー単位）で HTTP キャッシュをサポート
• AI Code Tracking API: エンドポイントで HTTP キャッシュをサポート

キャッシュの仕組み

1. 初回リクエスト: サポート対象の任意のエンドポイントへリクエストを送信
2. ETag を含むレスポンス: API はレスポンスに ETag ヘッダーを含めて返す
3. 後続リクエスト: If-None-Match ヘッダーに ETag の値を設定して送信
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 ヘッダーが含まれます
• データに変更がない場合に 304 Not Modified を受け取れるよう、後続のリクエストに If-None-Match ヘッダーを付与してください

利点

• 帯域幅の使用量を削減: 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:            # Exponential backoff: 1s, 2s, 4s, 8s, 16s            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 と AI Code Tracking API の場合:

これらの API は ETag を用いた HTTP キャッシュに対応しています。ETag を使って帯域幅の使用を抑え、不要なリクエストを避ける方法は、上記の Caching セクションを参照してください。

主なメリット:

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

Analytics API では、より良いキャッシュ効果のために、タイムスタンプの代わりに日付ショートカット（7d、30d）を使用してください。

4. 利用状況を監視する

制限内に収めるためにリクエストのパターンを追跡する:

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

5. バッチ処理は賢く

ページネーション対応のエンドポイントでは：

• 1回のリクエストでより多くのデータを取得できるよう、適切なページサイズを選ぶ
• Analytics API の by-user エンドポイントでは、特定ユーザーを絞り込むために users パラメータを使う
• 大規模なデータ抽出には、可能であれば CSV エンドポイントを使う（効率的にデータをストリーミング）

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

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

• Admin API /teams/daily-usage-data: 1時間に1回までポーリング (データは毎時集計)
• Admin API /teams/filtered-usage-events: 1時間に1回までポーリング (データは毎時集計)
• Admin API /organizations/pooled-usage: 1時間に1回までポーリング (データは毎時集計)
• Admin API /organizations/filtered-usage-events: 1時間に1回までポーリング (データは毎時集計)
• Analytics 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) {      // Rate limited - implement backoff      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Invalid API key      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": "不正なリクエスト",  "message": "一部のユーザーがチームに含まれていません"}

401 Unauthorized

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

{  "error": "未認証",  "message": "無効なAPIキー"}

403 Forbidden

API key は有効ですが、権限が不足しています (例: 非エンタープライズプランでエンタープライズ専用機能を使用している場合) 。

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

404 Not Found

要求されたリソースは見つかりません。

{  "error": "見つかりません",  "message": "リソースが見つかりません"}

429 リクエスト過多

レート制限を超えました。指数バックオフを実装してください。

{  "error": "リクエスト過多",  "message": "レート制限を超過しました。しばらくしてから再度お試しください。"}

500 内部サーバーエラー

サーバー側でエラーが発生しました。継続する場合はサポートにお問い合わせください。

{  "error": "内部サーバーエラー",  "message": "予期しないエラーが発生しました"}