Data API

Data API (bu sayfada daha önce Server API adıyla belgelenmişti), arka ucunuzun TRACIO'nun workspace'iniz için hâlihazırda topladığı kimlik tespiti verilerini okumasını sağlar: bir ziyaretçinin geçmişi, tekil oturumlar ve kısa pencereli velocity sayaçları. Birkaç rota da yazar — hesap kayıtları, özel alanlar ve liste girdileri — böylece arka ucunuz TRACIO'nun bildiklerini zenginleştirebilir.

Webhooks sayfasının yerini almaz, onu tamamlar:

Her iki yüzey de Pro planı ve üzerinde kullanılabilir.

Temel URL

https://api.tracio.ai/v2

Bu, tarayıcı uç noktasından (edge.tracio.ai) ve panelden (app.tracio.ai) farklı bir sunucudur. Üçü de ayrıdır: tarayıcı genel anahtarınızla edge ile, arka ucunuz ise gizli anahtarınızla Data API ile konuşur.

v1'den geçiş

/v1 rotaları kaldırıldı. /v2 kullanın: rotalar aynıdır ve her JSON anahtarı ile sorgu parametresi snake_case biçimindedir (visitor_id, risk_score, min_risk_score). Kendi fields ve labels sözlüklerinizin içindeki anahtarlar sizin verinizdir ve özgün yazımlarını korur. JavaScript SDK'sı camelCase arayüzünü korur.

Kimlik doğrulama

Her istek gizli anahtarınızı bir bearer token olarak taşır:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Data API yalnızca sunucudan sunucuya kullanılır. CORS başlıkları bilinçli olarak döndürülmez; bu yüzden bir tarayıcı onu çağıramaz — gizli anahtarınızı istemci tarafı koddan uzak tutan da budur. Gizli anahtarı asla tarayıcıya göndermeyin.

Gizli anahtar edinme

Panelde API Keys altında, secret türünü seçerek oluşturun.

• Anahtarın tamamı, oluşturma sırasında tam olarak bir kez gösterilir. Bizim tarafımızda yalnızca bir hash saklanır; bu nedenle kaybolan bir anahtar kurtarılamaz — onun yerine rotasyona sokun.
• Gizli bir anahtar tracio_sk_ ve ardından 43 karakter, toplam 53 karakter biçimindedir. Panel, anahtarları birbirinden ayırabilmeniz için onu ilk birkaç karakteriyle listeler.
• Gizli anahtarlar Pro planı veya üzerini gerektirir; tarayıcı ajanının kullandığı genel anahtar ise ayrı, gizli olmayan, 40 karakterlik bir değerdir.
• Bir anahtar bir ortama bağlıdır: üretim anahtarı staging'deki bir ziyaretçiyi görmez — yanıt, var olmayan veride olduğu gibi tam olarak 404'tür.

Gizli anahtar rotasyonu

Rotasyon yeni bir anahtar üretir ve eskisini 7 gün boyunca çalışır durumda tutar; böylece kesinti yaşamadan geçiş yapabilirsiniz. Yeni anahtarı yayına alın, trafiğin ona geçtiğini doğrulayın ve eskisinin süresinin dolmasını bekleyin. Genel anahtarlar rotasyona sokulamaz — bunlar gizli değildir ve tasarım gereği sayfanızın kaynağında görünürler.

Uç noktalar

Aynı anahtar ve sunucu, karar API'lerini de sunar; hepsi snake_case biçimindedir:

Sonuçları size webhook olayları olarak da ulaşır: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked ve affiliate_threshold_crossed.

Sondaki eğik çizgi kabul edilir ve yok sayılır. Bilinmeyen bir yol ya da yanlış bir yöntem, her şeyde olduğu gibi aynı JSON hata zarfını döndürür; asla bir HTML veya düz metin sayfası değil.

Zaman penceresi

Her okuma, iki isteğe bağlı sorgu parametresiyle denetlenen bir zaman penceresiyle sınırlıdır:

• to olarak verilen yalın bir tarih o günün tamamını kapsar.
• Bunun dışındaki her şey 400 invalid_request ve time must be YYYY-MM-DD or RFC3339 mesajıyla reddedilir.
• Hiçbirini geçmediğinizde pencere, şimdi biten, planınızın tam saklama süresidir.
• Planınızın izin verdiğinden daha geriye uzanan bir pencere reddedilmek yerine sessizce kırpılır. Fiilen kullanılan pencere her zaman meta içinde bildirilir; bu yüzden isteğinizin harfi harfine karşılandığını varsaymak yerine meta.from ve meta.to alanlarını kontrol edin.

Bir ziyaretçiyi arama

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Yanıt toplu geçmişi taşır ve en son oturumu gömer; böylece yaygın durum iki değil tek bir istek gerektirir:

{
  "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "first_seen_at": "2026-05-02T10:11:12Z",
  "last_seen_at": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognito_visits": 3,
  "unique_ips": 5,
  "unique_countries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "max_risk_score": 63,
    "avg_bot_score": 12.5,
    "bot_sessions": 7,
    "last_decision": "real"
  },
  "network": {
    "vpn_seen": false,
    "proxy_seen": false,
    "tor_seen": false,
    "datacenter_seen": true,
    "proxy_detected_seen": true,
    "last_isp": "Deutsche Telekom",
    "last_real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" }
  },
  "last_session": {
    "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "account_id": "user_8842",
    "account": { "id": "user_8842", "email": "ann@example.com", "display_name": "Ann Lee" },
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "fields": { "order_ref": "A-1029" },
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "gpu": "Apple M2",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "connection_type": "residential",
      "proxy_detected": true,
      "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" },
      "asn": 3320
    },
    "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 },
    "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
    "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "14.5.0" },
    "extensions": [
      {
        "slug": "ublock-origin",
        "name": "uBlock Origin",
        "category": "adblock",
        "risky": false,
        "store_url": "https://chromewebstore.google.com/detail/cjpalhdlnbpafiamejdnhcphjbkeiagm"
      }
    ],
    "bot": { "result": "human", "score": 4.5, "antidetect_score": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "match_type": "exact",
      "match_confidence": 0.99
    },
    "device_info": {
      "device_id": "d_4f9c2e",
      "cross_browser": true,
      "confidence": 0.88,
      "linked_browsers": 2
    },
    "decision": { "action": "real", "risk_score": 12, "suspect_score": 3 }
  },
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Saklama penceresi içinde verisi bulunmayan bir ziyaretçi, visitor not found in the retention window mesajıyla 404 not_found döndürür — bu entegrasyonunuzdaki bir hata değildir; ziyaretçinin yeni olduğu ya da verisinin süresinin dolduğu anlamına gelir.

Karar alanları

Oturum iki karar taşır ve bunlar farklı sorulara yanıt verir — istemcinin otomatikleşmiş olup olmadığı ve risk motorunun genel olarak neye vardığı:

bot.score ve decision.risk_score değerlerinin ikisi de 0..100 aralığındadır. Business ve üzerinde guidance, bunları allow → challenge → review → deny merdiveni üzerinde senaryo başına önerilere çevirir — her basamağın ne anlama geldiği için Guidance bölümüne bakın. Değerler ve ölçekler aynı ziyaretin v3 webhook gövdesiyle eşleşir ve guidance aynı kurallarla hesaplanır.

Bir ziyaretçinin oturumlarını listeleme

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&min_risk_score=50"

Oturumlar en yeniden başlayarak döner:

{
  "items": [
    {
      "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "next_cursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "has_more": true,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Sayfalama

Sayfalama imleç tabanlıdır. page veya offset parametresi yoktur: aldığınız next_cursor değerini cursor olarak geri gönderin ve has_more true olduğu sürece devam edin. Son sayfa next_cursor alanını hiç içermeyebilir; bu yüzden o alanı zorunlu yapmayın.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v2/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Data API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.has_more ? page.next_cursor : undefined
  } while (cursor)

  return sessions
}

İmleci opak kabul edin — içeriği bir uygulama ayrıntısıdır ve değişebilir. Düzenlenmiş bir imleç, 400 invalid_request ve malformed cursor mesajıyla reddedilir.

Cihaz bilgileri

User-Agent'tan alınan tarayıcı ve işletim sisteminin yanında bir oturum, ziyaretçinin tarayıcısının makine hakkında bildirdiklerini de taşır; bizim tarafımızda temizlenmiş olarak. Ziyaret böyle veri taşımadığında her alan bulunmaz, bu yüzden her birini isteğe bağlı sayın.

Tarayıcı uzantıları

extensions, ziyaret sırasında saptanan tarayıcı uzantılarını listeler — Pro ve üzeri. Her girdi bir nesnedir:

Bir bulgu, ancak güven denetimlerimizden geçtikten sonra bildirilir — her yoklamaya "kurulu" yanıtını veren bir ortam ya da on iki addan uzun bir küme, güvenilmez sayılarak elenir. Bu yüzden boş ya da eksik bir liste "kurulu uzantı yok" değil, "doğrulayabildiğimiz bir şey yok" demektir. Bunu bir envanter olarak değil, bir kanıt olarak okuyun.

Özel alanlar

fields, entegrasyonunuzun ziyarete eklediği özel anahtar-değer çiftlerini içerir — bir sipariş referansı, bir plan adı, bir ödemenin sonucu. Anahtarlar ve değerler her zaman dizedir: eklediğiniz bir sayı ya da boolean değer metin biçiminde döner. Oturumun geri kalanı gibi, API erişimi olan her planda (Pro ve üzeri) kullanılabilir ve ziyaretin hiç alanı yoksa yer almaz.

fields ziyaret anında kopyalanmaz, her istekte canlı olarak okunur. Ziyaretten sonra eklenen alanlar (Ziyaretten sonra alan ekleme bölümüne bakın) da burada görünür; bu yüzden aynı ziyaret için fields, webhook'un ilettiğinden fazlasını içerebilir.

Özel alanlara ad, e-posta adresi veya telefon numarası gibi kişisel veriler koymayın — bunların yerine kendi sistemlerinizin çözümleyebileceği bir referans ekleyin ve hesabın kim olduğunu bir hesap kaydı olarak gönderin (aşağıda).

Hesap kaydı

account, ziyaretin arkasındaki hesap için sizin kaydınızdır — o account_id için POST /v2/accounts/metadata üzerinden en son gönderdiğiniz:

{
  "account": { "id": "user-42", "email": "ann@example.com", "display_name": "Ann Lee" }
}

Kayıt her istekte canlı olarak okunur; bu yüzden bir ad değişikliği eski ziyaretlerde de görünür: blok, hesabı ziyaret anındaki hâliyle değil, şimdiki hâliyle tanımlar. API erişimi olan her planda (Pro ve üzeri) kullanılabilir. Kayıtla birlikte gönderdiğiniz etiketler döndürülmez.

Ziyaretin bağlı bir hesabı olmadığında, onun için bir kayıt bulunmadığında (ya da boş değerler göndererek kaydı temizlediğinizde) ve — nadiren — kayıt okunamadığında blok bulunmaz: oturum, isteği başarısız kılmak yerine yine de eksiksiz döndürülür; bu yüzden eksik bir bloğu "bu hesabın e-postası yok" olarak değil, "bilinmiyor" olarak değerlendirin. Webhook'lar bu bloğu taşımaz.

Tek bir oturumu getirme

En yenisi:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Bu, çıplak bir oturum nesnesi döndürür — bir dizi değil ve bir zarfa sarılmış da değil. Pencerede hiç oturumu olmayan bir ziyaretçi, no sessions for this visitor in the retention window ile 404 not_found döndürür.

Ya da webhook payload'ında da görünen tanımlayıcı olan request_id ile:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitor_id=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

visitor_id burada isteğe bağlıdır, ancak biliyorken göndermek aramayı belirgin biçimde hızlandırır.

identification.drift_score — hesap ele geçirme kararının dayandığı düzleştirilmiş davranış skoru, Business ve üzeri — yalnızca bu tek oturum okumasıyla döndürülür. Davranış sapması ziyaret sırasında, ilk kimlik tespitinden sonra ölçülür; bu yüzden liste ve en son oturum rotaları onu içermez. Davranışı hiç değerlendirilmemiş bir ziyaretin drift_score değeri yoktur. Aynı değer size account_takeover webhook'u üzerinden de ulaşır.

Düzeltilmiş bir ziyaret için hangi yanıtı alırsınız

Bir ziyaret webhook ile birden fazla kez teslim edilebilir: önce primary, ardından daha yavaş sinyaller ve davranışsal kanıtlar geldikçe late veya correction — ve sonraki bir faz önceki kararı tersine çevirebilir. Data API primary kaydından yanıt verir. Sonraki fazlar ona geri birleştirilmez; bu yüzden düzeltilmiş bir ziyaret için son webhook daha yeni yanıttır. Ziyaretten dakikalar sonra harekete geçiyorsanız, buradaki taze bir okuma yerine en son aldığınız fazı tercih edin.

Bir şey ters yönde işler: hesap ele geçirme dedektörü bir ziyaret için tetiklendikten sonra buradaki guidance bunu yansıtır, oysa aynı ziyaretin identification webhook gövdeleri bu ekseni taşımaz — o, ayrı account_takeover teslimatıyla gelir.

Velocity

Velocity, "bu ziyaretçi son zamanlarda ne kadar iş yaptı" sorusuna yanıt verir — credential stuffing, kart deneme ve toplu kayıtların biçimi budur.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window, 1h, 24h veya 7d değerlerini kabul eder ve varsayılanı 24h'dir. Başka herhangi bir değer, 400 invalid_request ve window must be one of: 1h, 24h, 7d ile reddedilir.

{
  "window": "1h",
  "events": 37,
  "unique_ips": 9,
  "unique_countries": 3,
  "unique_accounts": 12,
  "bot_events": 4,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

unique_accounts, bu cihaz için gönderdiğiniz farklı linkedId değerlerini sayar — bkz. Hesap eşleme. bot_events Business ve üzerindedir; Pro'da anahtar bulunmaz.

Hesap meta verileri

TRACIO hesaplarınızı yalnızca sitenizin linkedId olarak geçirdiği kimlikle tanır — usr_8412 gibi opak bir dize. İnsan tarafından okunabilir etiketleri bir kez gönderin; o hesabı gösteren her panel ekranı ham kimlik yerine adı veya e-postayı gösterir ve oturum nesnesi bunları account bloğunda döndürür. Buradaki hiçbir şey tespiti veya skorlamayı etkilemez; bu bir görüntüleme katmanıdır.

curl -s -X POST "https://api.tracio.ai/v2/accounts/metadata" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"accounts":[
        {"account_id":"usr_8412","email":"ann@example.com","display_name":"Ann Lee","labels":{"tier":"vip"}},
        {"account_id":"usr_9130","display_name":"Bob Ray"}
      ]}'

{ "updated": 2 }

• Bir hesap hakkındaki kişisel verilerin yeri burasıdır — fields değil. Buraya gönderilen bir e-posta veya ad yalnızca workspace'inizin hesap kaydında yaşar: ziyaret başına saklanmaz, sayfaya yazılmaz ve tek bir gönderim o hesabın her ziyaretini günceller.
• Kapsam, anahtarın workspace'i ve ortamıdır. Bir staging anahtarı, bir üretim anahtarının aynı hesap kimliği için yazdığının üzerine asla yazmaz.
• Her gönderim bir yama değil, tam bir üzerine yazmadır. Atladığınız alanlar boş saklanır — her seferinde kaydın tamamını gönderin. Bir değeri temizlemenin yolu da budur.
• Bilinmeyen alanlar 400 invalid_request ile reddedilir ve tek bir hatalı girdi tüm kümeyi reddeder — hata onun konumunu belirtir. Tek bir kümede yinelenen hesap kimlikleri sorun değildir: sonuncusu kazanır.

Sınırlar: istek başına 1000 hesap, 1 MiB gövde, account_id ≤ 256 karakter, email ≤ 320, display_name ≤ 256, anahtarları ≤ 64 ve değerleri ≤ 256 karakter olan en fazla 16 etiket.

Ziyaretten sonra alan ekleme

Tarayıcı yalnızca sayfanın oluşturma anında bildiğini gönderebilir — bir sipariş kimliği, asla bir ödeme kontrolünün sonucunu ya da daha sonra netleşen başka bir şeyi değil. Bu rota o boşluğu doldurur: ziyareti zaten taşıdığı bir alanla bulun ve ona sunucu tarafında daha fazla alan ekleyin.

curl -s -X POST "https://api.tracio.ai/v2/events/fields" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"},"fields":{"amount":"120.00"}}'

{ "updated": 1 }

• match, ziyareti request_id ile değil, zaten sahip olduğu bir alanla bulur; anahtarınızın workspace'i ve ortamı içinde.
• Arama penceresi 24 saattir. Daha eski bir ziyaret 404 not_found döndürür — alanı sonuç netleştikten kısa süre sonra yazın.
• updated farklı ziyaretleri sayar. Yalnızca match'iniz birden fazla ziyarete denk geldiğinde 1'in üzerine çıkar — tek bir siparişe veya sepete özgü olmayan bir anahtar/değer çifti. 100'den fazla olaya denk gelen bir match, keyfî bir alt kümeye uygulanmak yerine 400 invalid_request ile reddedilir.
• Burada yazılan alanlar panelde server etiketiyle görünür ve tarayıcının aynı anahtarla yazdığı bir değere göre önceliklidir.
• Eşleşme olmaması boş bir 200 değil, 404 not_found'dur.

Sınırlar tarayıcı kanalıyla aynıdır: çağrı başına 50 alan, anahtarlar ≤ 40 bayt, değerler ≤ 500 bayt — karakter değil, bayt — anahtar karakter kümesi A-Za-z0-9_.:-, 1 MiB gövde.

Alanları silme

Özel alanları siler — asla ziyaretin kendisini değil. Bir ziyarete artık bağlı kalmasına ihtiyaç duymadığınız değerler, örneğin bir sipariş tutarı için kullanın. Zaten gönderilmiş webhook'lar ve zaten alınmış dışa aktarımlar değişmez.

# by request_id — clears every field on this one visit
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31"}'

# by match — clears "order_ref" from every visit currently holding "A-1029"
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"}}'

{ "deleted": 1 }

• request_id ve match birbirini dışlar — ikisini birden göndermek ya da hiçbirini göndermemek 400 invalid_request olur. match, ekleme ile aynı 24 saatlik pencereyi ve aynı 100 olay tavanını kullanır.
• deleted, ziyaretten kaldırılan alanları (request_id ile) ya da alanın kaldırıldığı ziyaretleri (match ile) sayar.
• Hiçbir şey kalmadıktan sonra yeniden çağırmak 404 not_found döndürür.

Workspace listeleri

Operatörlerinizin panelde yönettiği listelerin aynısı, kendi arka ofisinizden erişilebilir. Bir listenin türü, eşleşen bir ziyaretteki eylemidir — block, manual_review, challenge, allow — ve modu eylemin uygulanıp uygulanmayacağına karar verir: observe yalnızca eşleşmeleri sayar, enforce onu guidance'a uygular (list ekseni). Listeler ve modları panelde oluşturulur; Data API listeleri okur ve girdi ekleyip kaldırır.

curl -s "https://api.tracio.ai/v2/lists" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

[
  {
    "id": "7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60",
    "name": "Chargeback accounts",
    "type": "block",
    "mode": "enforce",
    "entries_count": 128
  }
]

# ban an account for 30 days
curl -s -X POST "https://api.tracio.ai/v2/lists/7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60/entries" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"value":"usr_8412","value_type":"linked_id","ttl_minutes":43200}'

{
  "id": "02b4c8d1-6e7f-4a90-b1c2-d3e4f5a6b7c8",
  "value": "usr_8412",
  "value_type": "linked_id",
  "expires_at": "2026-10-19T12:00:00Z",
  "propagation": "immediate"
}

Bir girdiyi aynı gövdeyle POST /v2/lists/{list_id}/entries/delete adresinde kaldırın; yanıt { "removed": true, "propagation": "immediate" } olur.

• value_type, değerin neyle eşleştirildiğidir: linked_id, visitor_id, device_id, ip, cidr veya country. Türüne göre ayrıştırılamayan bir değer 400 invalid_request olur.
• Birkaç liste eşleştiğinde en belirgin tür karar verir — linked_id → visitor_id → device_id → ip → cidr → country — ve onun içinde en katı eylem kazanır.
• ttl_minutes isteğe bağlıdır. Atlanırsa listenin varsayılan TTL'i uygulanır; hiçbiri yoksa girdinin süresi asla dolmaz (expires_at null olur). Bir girdiyi yeniden eklemek onu yeniler.
• propagation değişikliğin ne zaman canlı olduğunu söyler: immediate ya da ttl — yaklaşık beş dakika içinde.
• Orada olmayan bir değeri silmek removed: false ile 200 olur; 404 bilinmeyen bir liste için ayrılmıştır.

Yanıt kuralları

Eksik bir alan "veri yok" demektir, asla sıfır değil. Değeri olmayan alanlar 0, "" ya da null olarak gönderilmek yerine tamamen çıkarılır: yepyeni bir ziyaretçinin match_confidence değeri, temiz bir ziyaretin de antidetect_score veya suspect_score değeri yoktur. Bilinçli tek istisna, sıfır olduğunda bile her zaman bulunan bot.score'dur. Alanları savunmacı biçimde okuyun.

Payload planınıza bağlıdır. API erişimi Pro'dan başlar ve Pro temel oturumu alır — tanımlayıcılar, zaman damgası, URL, IP, user agent, tarayıcı, işletim sistemi, cihaz, coğrafi konum, ağ, bot, kimlik tespiti ve karar — ve bunlarla birlikte identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields ve account alanlarını. Business ve Enterprise ise geo.isp, network.asn, network.real_ip, decision.suspect_score, identification.drift_score, reasons, behavior, guidance, device_info, spoofing, os_environment, screen, locale, client_hints ve environment alanlarını ekler. Kişi düzeyindeki alanlar (person_id, reputation, linked_accounts_count, linked_visitors_count) Business ve Enterprise'a ayrılmıştır ve kişi katmanı etkinleştirildiğinde görünecektir — bugün gözlem modunda çalışıyor ve bu alanlar iletilmiyor. Pro planında bir Business alanının bulunmaması hata değildir.

Sinyal düzeyindeki iç ayrıntılar hiçbir planda döndürülmez: tekil sinyal adları, ağırlıkları, bir kararın ardındaki eşikler, ham sinyal değerleri ve skor dökümleri bizde kalır. Tersine mühendislikle girdilerine dönüştürülebilen bir skor, savunma olarak işlevini yitirir.

Hatalar

Her başarısızlık tek bir zarf kullanır:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "request_id": "8f14e45fceea167a5a36dedd"
  }
}

Bu request_id, ziyaret tanımlayıcısı değildir. İki farklı değer aynı adı paylaşır: bir oturum payload'ının içinde request_id, webhook'un ilettiğiyle aynı olan ziyaretin UUID'sidir; bir hata zarfının içinde ise her HTTP çağrısı için üretilen 24 karakterlik bir izleme tanımlayıcısıdır. İzleme tanımlayıcısı ayrıca başarılı olsun olmasın her yanıtta X-Request-Id başlığında geri döner. Destek ekibiyle iletişime geçtiğinizde onu da ekleyin — tam olarak sizin çağrınızı böyle buluyoruz.

Kontroller sabit bir sırayla yapılır — önce anahtar, sonra plan, sonra limitler — bu yüzden hatalı anahtarla gelen bir istek her zaman önce anahtarı bildirir, asla bir kota sorununu değil. Başka bir workspace'in verisi, var olmayan veriden ayırt edilemez: 403 değil, 404 verir.

İki 401 durumu bilinçli olarak farklı okunur: missing Authorization: Bearer <secret key> başlığın hiç gelmediği anlamına gelirken invalid or revoked API key başlığın geldiği ama eşleşmediği anlamına gelir. 402 ise Data API requires the Pro plan or higher mesajını taşır.

429 ve 503'ü artan bir beklemeyle yeniden deneyin; diğer 4xx yanıtlarını yeniden denemek anlamsızdır — isteğin kendisinin düzeltilmesi gerektiği anlamına gelirler.

Hız sınırları ve kotalar

Anahtarın tanındığı yanıtlar mevcut durumunuzu taşır (401 ve 402 yanıtları taşımaz; günlük kotası olmayan Enterprise de kota başlıkları almaz):

• Kısa patlamalara izin verilir: saniyelik limit, reddetmeye başlamadan önce sürdürülen hızın üç katına kadar tolerans gösteren bir token bucket'tır.
• Saniyelik hızı aştığı için reddedilen bir istek günlük kotayı tüketmez; bu yüzden bir patlama günün bütçesini yiyemez.
• Data API limitleri kimlik tespiti trafiğinden ayrı sayılır. Kendi geçmişinizi okumak, bedelini ödediğiniz kimlik tespitlerini asla harcamaz.

Sonraki Adımlar

• Webhooks — her kimlik tespitini gerçekleştiği anda alın
• Hesap eşleme — kendi hesap kimliğinizi bir cihaza iliştirin
• Bot Tespiti — bot kararının nasıl üretildiği
• Gizlilik ve GDPR — veri sahibi taleplerinin işlenmesi