İçeriğe geç
ajan.io

Belgeler menüsü

Bu sayfada

Usage Export'a giriş

Workspace kullanım verilerini CSV veya JSON olarak dışa aktarmak için Usage Export API'yi kullanın.

Usage Export API, workspace yöneticilerinin kullanıcılar, agent'lar, API anahtarları, projeler, modeller ve iş akışları için kullanım verilerini dışa aktarmasını sağlar. Raporlamayı otomatikleştirmek veya verileri harici bir analitik sisteme çekmek istediğinizde kullanın.

Bu dışa aktarımları ajan arayüzünden de oluşturabilirsiniz. Bkz. Usage Exports.

Prerequisites

Usage Export API'yi kullanmak için şunlara ihtiyacınız vardır:

  • Workspace Admin Permission: Yalnızca workspace yöneticileri usage export izinlerine sahip API anahtarları oluşturabilir ve web arayüzü üzerinden veri dışa aktarabilir.
  • API Key with USAGE_EXPORT_API Scope: Dışa aktarım işlevlerine erişim için özel izin

Önemli güvenlik uyarısı: USAGE_EXPORT_API kapsamına sahip bir API anahtarına erişimi olan kullanıcılar, normalde bu verileri görüntüleme yetkisi olmasa bile tüm alanlar için workspace kullanım verilerini dışa aktarabilir. Bu izni yalnızca güvenilir kullanıcılara verin.

Programatik dışa aktarım

Available Endpoints

Usage Export API çeşitli veri türlerine erişim sağlar:

POST /export/users
POST /export/agents
POST /export/api-keys
POST /export/projects
POST /export/models
POST /export/workflows

Eski assistants dataType, agents ile aynı veriyi döndürür. POST /export/assistants bir alias olarak kullanılabilir kalır.

Her endpoint ayrıca açık çıktı biçimi rotalarını da destekler:

POST /export/{dataType}/csv
POST /export/{dataType}/json

Authentication

Tüm API istekleri Bearer token kimlik doğrulaması gerektirir:

bash
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Format

Zaman belirtimi ve saat dilimi işleme:\ API, sağladığınız date parametresindeki tam zamanı kullanır ve bunları timezone parametresinde belirtilen yerel zamanlarınız olarak işler. date değerinin sonuna "Z" eklerseniz (UTC/Zulu zamanı), timezone'un iki kez uygulanmasını önlemek için otomatik olarak kaldırılır.

json
{
  "from": {
    "date": "2024-01-01T00:00:00.000",
    "timezone": "Europe/Berlin"
  },
  "to": {
    "date": "2024-01-31T23:59:59.999", 
    "timezone": "UTC"
  },
  "group_by": "model"
}

group_by isteğe bağlıdır. Desteklenen değerler dışa aktarım türüne göre değişir:

ExportSupported group_by values
Usersmodel
Agents / Assistantsmodel
API keysmodel
Modelssource; yalnızca BYOK workspace'leri için deployment
ProjectsDesteklenmez
WorkflowsDesteklenmez

Desteklenmeyen bir group_by değeri içeren istekler 400 Bad Request döndürür.

Response Format

CSV Response

CSV endpoint'leri bir dosya yolu ve indirme URL'si döndürür:

json
{
  "success": true,
  "data": {
    "filePath": "agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv",
    "downloadUrl": "https://storage.example.com/signed-url",
    "dataType": "agents",
    "recordCount": 1250,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000+01:00",
      "to": "2024-01-31T23:59:59.999"
    }
  }
}

JSON Response

JSON endpoint'leri satırları doğrudan döndürür:

json
{
  "success": true,
  "data": [
    {
      "period_start": "2024-01-01",
      "period_end": "2024-01-31",
      "org_id": "workspace-id"
    }
  ],
  "metadata": {
    "dataType": "users",
    "recordCount": 1,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000Z",
      "to": "2024-01-31T23:59:59.999Z"
    }
  }
}

Error Response

json
{
  "message": "No usage data found for the selected period",
  "code": "NOT_FOUND"
}

Example Requests

Agent kullanımını dışa aktar

bash
curl -X POST "https://api.ajan.io/export/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "date": "2024-01-01T00:00:00.000",
      "timezone": "UTC"
    },
    "to": {
      "date": "2024-01-31T23:59:59.999",
      "timezone": "UTC"
    }
  }'

Kullanıcı kullanımını dışa aktar

bash
curl -X POST "https://api.ajan.io/export/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "date": "2024-01-01T00:00:00.000",
      "timezone": "UTC"
    },
    "to": {
      "date": "2024-01-31T23:59:59.999",
      "timezone": "UTC"
    }
  }'

Export Limits

Her Usage Export API isteği en fazla 1.000.000 kullanım satırını tarayabilir. Bu limit varsayılan, CSV ve JSON endpoint'leri için geçerlidir.

Limiti aşan istekler USAGE_EXPORT_TOO_LARGE koduyla 400 Bad Request döndürür. Hata mesajı satır limitini belirtir; details içinde limit olarak yer alır. Daha kısa bir tarih aralığı seçin ve sonuçları birleştirin.

Rate Limits

Usage Export API, workspace ve API anahtarı başına uygulanan bir istek rate limit'ine tabidir. Completion endpoint'lerine uygulanan token limiti burada geçerli değildir.

  • Requests per Minute: 500 Requests/Min

Endpoint Details

Troubleshooting

Common Errors

400 Bad Request - Desteklenmeyen group_by

json
{
  "message": "group_by=deployment is not supported for users exports",
  "code": "BAD_REQUEST"
}

Çözüm: Dışa aktarım türünün desteklediği bir group_by değeri kullanın veya alanı atlayın.

400 Bad Request: Dışa aktarım çok büyük

json
{
  "message": "Export too large: more than 1,000,000 usage rows for the selected date range. Try a shorter date range and combine the CSV files.",
  "code": "USAGE_EXPORT_TOO_LARGE",
  "details": {
    "usageRows": 1500000,
    "limit": 1000000
  }
}

Çözüm: Daha kısa bir tarih aralığı seçin ve sonuçları birleştirin.

401 Unauthorized

json
{
  "message": "The provided API key is invalid."
}

Çözüm: API anahtarınızın doğru olduğundan ve USAGE_EXPORT_API iznine sahip olduğundan emin olun.

404 No Data Found

json
{
  "message": "No usage data found for the selected period",
  "code": "NOT_FOUND"
}

Çözüm: Seçilen zaman aralığını kontrol edin — bu dönemde etkinlik olmamış olabilir.

Security and Privacy

Privacy Settings

Workspace yapılandırmasına bağlı olarak bazı veriler hariç tutulabilir:

  • User-identifying Data: Gizlilik ayarları nedeniyle hariç tutulabilir
  • Leaderboards: Tam kullanıcı verisi için workspace'te etkin olmalıdır

Best Practices

  1. Secure API Key Storage: Ortam değişkenleri veya güvenli anahtar yönetimi kullanın
  2. Regular Rotation: API anahtarlarını düzenli olarak yenileyin
  3. Minimal Permissions: Yalnızca gerekli kapsamları verin
  4. Monitoring: API anahtarlarınızın kullanımını izleyin

Compliance

Usage Export API, uyumluluk gereksinimlerine yardımcı olur:

  • Audit Trails: API kullanımının eksiksiz takibi
  • Data Export: GDPR veri erişim hakları desteği
  • Transparency: Workspace kullanımı hakkında net içgörüler

Support

Usage Export API hakkında sorularınız için destek ekibimizle iletişime geçin veya eksiksiz API belgelerine bakın.

ajan, API anahtarınızı korumak ve uygulamalarınızın güvenliğini sağlamak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. Daha fazla bilgi için API Key Best Practices kılavuzuna bakın.