Gambaran Umum Cursor APIs

Cursor menyediakan beberapa API untuk mengakses data tim Anda, agen coding bertenaga AI, dan analitik secara terprogram.

API yang Tersedia

API Agen Cloud dan SDK menjalankan alur kerja agen Cursor (konteks ruang kerja, alat, perintah, dan pengeditan). Keduanya bukan API mandiri untuk inferensi model atau penyelesaian chat. Cursor Router memilih model untuk menjalankan agen tersebut saat Anda menggunakan Auto / auto-smart; lihat Router di TypeScript SDK atau Python SDK.

Autentikasi

Semua API Cursor mendukung Otentikasi Dasar. API Agen Cloud juga mendukung token Bearer — pilih yang paling mudah digunakan dengan klien HTTP Anda.

Otentikasi Dasar

Gunakan kunci API Anda sebagai nama pengguna untuk Otentikasi Dasar (biarkan kata sandi kosong):

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

Atau, atur header Authorization secara langsung:

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

Autentikasi Bearer (API Agen Cloud)

API Agen Cloud juga menerima header Authorization: Bearer <key>. Kedua skema berfungsi sama — gunakan yang paling mudah dengan klien HTTP Anda:

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

Membuat Kunci API

Administrator tim dapat membuat dan mengelola kunci API melalui halaman API Keys di Dashboard.

Admin API & AI Code Tracking API

1. Buka cursor.com/dashboard → API Keys
2. Klik New API Key
3. Beri kunci API Anda nama deskriptif (misalnya, "Integrasi Dashboard Penggunaan")
4. Segera salin kunci API yang dihasilkan. Kunci API ini tidak akan ditampilkan lagi

Format kunci API: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scope yang diperlukan: admin:*

Analytics API

Buat kunci API di Cursor Dashboard → API Keys.

API Agen Cloud

Buat kunci API pengguna melalui Dashboard Cursor → Kunci API, atau gunakan kunci API akun layanan dari pengaturan tim.

Batas Laju

Semua API menerapkan pembatasan laju untuk memastikan penggunaan yang adil dan menjaga stabilitas sistem. Batas laju diterapkan per tim dan diatur ulang setiap menit.

Batas Laju berdasarkan API

Respons Batas Laju

Saat Anda melampaui batas laju, Anda akan menerima respons 429 Too Many Requests:

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

Caching

Beberapa API mendukung caching HTTP menggunakan ETag untuk mengurangi penggunaan bandwidth dan meningkatkan performa.

API yang Didukung

• Analytics API: Semua endpoint (tingkat tim maupun per pengguna) mendukung HTTP caching
• AI Code Tracking API: Endpoint mendukung HTTP caching

Cara Kerja Caching

1. Permintaan Awal: Buat permintaan ke endpoint yang didukung
2. Respons Mencakup ETag: API mengembalikan header ETag dalam respons
3. Permintaan Berikutnya: Sertakan nilai ETag dalam header If-None-Match
4. 304 Not Modified: Jika data tidak berubah, Anda akan menerima respons 304 Not Modified tanpa isi

Contoh

# Permintaan awalcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# Respons mencakup: ETag: "abc123xyz"# Permintaan berikutnya dengan ETagcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# Mengembalikan 304 Not Modified jika data belum berubah

Durasi Cache

• Durasi cache: 15 menit (Cache-Control: public, max-age=900)
• Respons menyertakan header ETag
• Sertakan header If-None-Match dalam permintaan selanjutnya untuk menerima 304 Not Modified jika data tidak berubah

Manfaat

• Mengurangi penggunaan bandwidth: Respons 304 tidak memiliki body
• Respons lebih cepat: Menghindari pemrosesan data yang tidak berubah
• Ramah terhadap Batas Laju: Respons 304 tidak mengurangi kuota Batas Laju
• Performa lebih baik: Sangat berguna untuk endpoint yang sering dicek secara berkala

Praktik Terbaik

1. Terapkan Exponential Backoff

Saat menerima respons 429, tunggu sebelum mencoba lagi dengan jeda yang semakin lama:

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:            # Backoff eksponensial: 1 dtk, 2 dtk, 4 dtk, 8 dtk, 16 dtk            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. Sebarkan Permintaan Seiring Waktu

Sebarkan panggilan API Anda dari waktu ke waktu, alih-alih mengirimkan permintaan secara tiba-tiba dalam jumlah besar:

• Jadwalkan tugas batch agar berjalan pada interval yang berbeda
• Tambahkan jeda antarpermintaan saat memproses set data besar
• Gunakan sistem antrean untuk meredam lonjakan traffic

3. Manfaatkan Caching

Untuk Analytics API dan AI Code Tracking API:

API ini mendukung HTTP caching dengan ETag. Lihat bagian Caching di atas untuk mengetahui cara menggunakan ETag guna mengurangi penggunaan bandwidth dan menghindari permintaan yang tidak diperlukan.

Manfaat utama:

• Mengurangi penggunaan bandwidth
• Respons lebih cepat saat data tidak berubah
• Tidak dihitung dalam Batas Laju (untuk respons 304)

Gunakan shortcut tanggal (7d, 30d) alih-alih stempel waktu untuk dukungan caching yang lebih baik di Analytics API.

4. Pantau Penggunaan Anda

Lacak pola permintaan agar tetap dalam batas penggunaan:

• Catat stempel waktu panggilan API dan kode respons
• Atur peringatan untuk respons 429
• Pantau tren penggunaan harian/mingguan
• Sesuaikan interval cek berkala berdasarkan kebutuhan aktual

5. Proses Batch dengan Bijak

Untuk endpoint dengan pagination:

• Gunakan ukuran page yang sesuai untuk mendapatkan lebih banyak data per permintaan
• Untuk endpoint Analytics API per pengguna: gunakan parameter users untuk memfilter pengguna tertentu
• Untuk ekstraksi data berukuran besar: gunakan endpoint CSV jika tersedia (data di-stream secara efisien)

6. Lakukan Cek secara Berkala pada Interval yang Tepat

Jangan terlalu sering melakukan cek secara berkala pada endpoint yang jarang diperbarui:

• Admin API /teams/daily-usage-data: Lakukan cek secara berkala maksimal sekali per jam (data diagregasikan setiap jam)
• Admin API /teams/filtered-usage-events: Lakukan cek secara berkala maksimal sekali per jam (data diagregasikan setiap jam)
• Admin API /organizations/pooled-usage: Lakukan cek secara berkala maksimal sekali per jam (data diagregasikan setiap jam)
• Admin API /organizations/filtered-usage-events: Lakukan cek secara berkala maksimal sekali per jam (data diagregasikan setiap jam)
• Analytics API: Gunakan pintasan tanggal (7d, 30d) untuk dukungan caching yang lebih baik
• AI Code Tracking API: Data diserap hampir secara real-time, tetapi cek secara berkala setiap beberapa menit sudah cukup

7. Tangani Error dengan Baik

Terapkan penanganan error yang tepat untuk semua panggilan 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) {      // Melebihi batas laju - terapkan backoff      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Kunci API tidak valid      throw new Error('Authentication failed');    }        if (response.status === 403) {      // Izin tidak memadai      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;  }}

Respons Error Umum

Semua API menggunakan kode status HTTP standar:

400 Permintaan Tidak Valid

Parameter permintaan tidak valid atau field wajib tidak ada.

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

401 Tidak Diotorisasi

Kunci API tidak valid atau tidak tersedia.

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

403 Forbidden

Kunci API valid, tetapi izin tidak mencukupi (misalnya, fitur Enterprise pada paket non-Enterprise).

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

404 Tidak Ditemukan

Sumber daya yang diminta tidak tersedia.

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

429 Terlalu Banyak Permintaan

Batas laju terlampaui. Terapkan jeda mundur eksponensial.

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

500 Kesalahan Server Internal

Terjadi kesalahan di sisi server. Hubungi dukungan jika masalah berlanjut.

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