Data API

Data API (जिसे यहाँ पहले Server API के नाम से प्रलेखित किया जाता था) आपके बैकएंड को वह पहचान डेटा पढ़ने देता है जो TRACIO आपके वर्कस्पेस के लिए पहले ही एकत्र कर चुका है: किसी विज़िटर का इतिहास, अलग-अलग सेशन, और छोटी विंडो वाले वेलोसिटी काउंटर।

यह Webhooks की जगह नहीं लेता, बल्कि उनका पूरक है:

दोनों सतहें Pro प्लान और उससे ऊपर उपलब्ध हैं।

बेस URL

https://api.tracio.ai/v1

यह ब्राउज़र एंडपॉइंट (edge.tracio.ai) और डैशबोर्ड (app.tracio.ai) से अलग होस्ट है। तीनों अलग-अलग हैं: ब्राउज़र आपकी पब्लिक कुंजी के साथ edge से बात करता है, और आपका बैकएंड आपकी सीक्रेट कुंजी के साथ Data API से।

प्रमाणीकरण

हर अनुरोध आपकी सीक्रेट कुंजी को bearer token के रूप में साथ ले जाता है:

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

Data API केवल सर्वर-टू-सर्वर है। CORS हेडर जान-बूझकर नहीं लौटाए जाते, इसलिए कोई ब्राउज़र इसे कॉल नहीं कर सकता — यही आपकी सीक्रेट कुंजी को क्लाइंट-साइड कोड से बाहर रखता है। सीक्रेट कुंजी को ब्राउज़र तक कभी न भेजें।

सीक्रेट कुंजी प्राप्त करना

इसे डैशबोर्ड में API Keys के अंतर्गत बनाएं, secret प्रकार चुनकर।

• पूरी कुंजी ठीक एक बार दिखाई जाती है, बनाते समय। हमारी ओर केवल एक हैश संग्रहीत होता है, इसलिए खोई हुई कुंजी वापस नहीं पाई जा सकती — उसकी जगह उसे रोटेट करें।
• सीक्रेट कुंजी tracio_sk_ और उसके बाद 43 वर्णों जैसी दिखती है, कुल 53। डैशबोर्ड इसे इसके पहले कुछ वर्णों से सूचीबद्ध करता है, ताकि आप कुंजियों में फ़र्क कर सकें।
• सीक्रेट कुंजियों के लिए Pro प्लान या उससे ऊपर आवश्यक है; ब्राउज़र एजेंट द्वारा उपयोग की जाने वाली पब्लिक कुंजी एक अलग, गैर-गुप्त 40-वर्ण मान है।

सीक्रेट कुंजी रोटेट करना

रोटेशन एक नई कुंजी जारी करता है और पुरानी को 7 दिन तक काम करने देता है, ताकि आप उसे बिना डाउनटाइम रोल आउट कर सकें। नई कुंजी डिप्लॉय करें, पुष्टि करें कि ट्रैफ़िक उस पर चला गया है, और पुरानी को समाप्त होने दें। पब्लिक कुंजियाँ रोटेट नहीं की जा सकतीं — वे गुप्त नहीं हैं और डिज़ाइन के अनुसार आपके पेज सोर्स में दिखती हैं।

एंडपॉइंट

हर रूट GET है। Data API में कोई राइट ऑपरेशन नहीं है: यह डेटा पढ़ता है, और आपका कॉन्फ़िगरेशन डैशबोर्ड में रहता है।

अंत में स्लैश स्वीकार किया जाता है और अनदेखा कर दिया जाता है। अज्ञात पथ या गलत मेथड वही JSON त्रुटि एनवेलप लौटाता है जो बाकी सब कुछ लौटाता है, कभी HTML या सादा-टेक्स्ट पेज नहीं।

समय विंडो

हर रीड एक समय विंडो से बंधा होता है, जिसे दो वैकल्पिक क्वेरी पैरामीटर नियंत्रित करते हैं:

• to के रूप में केवल तारीख देने पर वह पूरा दिन शामिल होता है।
• इसके अलावा कुछ भी 400 invalid_request और संदेश time must be YYYY-MM-DD or RFC3339 के साथ अस्वीकार कर दिया जाता है।
• जब आप दोनों में से कुछ नहीं भेजते, तो विंडो आपके प्लान की पूरी अवधारण अवधि होती है, जो इस क्षण पर समाप्त होती है।
• आपके प्लान की अनुमति से अधिक पीछे तक जाने वाली विंडो अस्वीकार नहीं की जाती, बल्कि चुपचाप सीमित कर दी जाती है। वास्तव में उपयोग की गई विंडो हमेशा meta में वापस बताई जाती है, इसलिए यह मान लेने के बजाय कि आपका अनुरोध अक्षरशः माना गया, meta.from और meta.to जांचें।

किसी विज़िटर को देखना

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

उत्तर समेकित इतिहास लाता है और नवीनतम सेशन को भी उसी में समाहित कर देता है, इसलिए सामान्य स्थिति में दो के बजाय एक ही अनुरोध चाहिए:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "proxyDetectedSeen": true,
    "lastIsp": "Deutsche Telekom",
    "lastRealIp": "203.0.113.7"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "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,
      "proxyDetected": true,
      "realIp": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" },
      "asn": 3320
    },
    "screen": { "width": 2560, "height": 1600, "colorDepth": 30, "pixelRatio": 2 },
    "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
    "clientHints": { "architecture": "arm", "bitness": "64", "platformVersion": "14.5.0" },
    "extensions": [
      {
        "slug": "ublock-origin",
        "name": "uBlock Origin",
        "category": "adblock",
        "risky": false,
        "storeUrl": "https://chromewebstore.google.com/detail/cjpalhdlnbpafiamejdnhcphjbkeiagm"
      }
    ],
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "deviceInfo": {
      "deviceId": "d_4f9c2e",
      "crossBrowser": true,
      "confidence": 0.88,
      "linkedBrowsers": 2
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

अवधारण विंडो के भीतर बिना किसी डेटा वाला विज़िटर 404 not_found और संदेश visitor not found in the retention window लौटाता है — यह आपके इंटीग्रेशन की त्रुटि नहीं है, इसका अर्थ है कि विज़िटर नया है या समय के साथ बाहर हो चुका है।

वर्डिक्ट फ़ील्ड

सेशन दो वर्डिक्ट लाता है, और वे अलग-अलग प्रश्नों का उत्तर देते हैं — क्या क्लाइंट स्वचालित था, और जोखिम इंजन ने कुल मिलाकर क्या निष्कर्ष निकाला:

bot.score और decision.riskScore दोनों 0..100 पर चलते हैं। Business और उससे ऊपर guidance इन्हें सीढ़ी allow → challenge → review → deny पर प्रति-परिदृश्य सलाह में बदल देता है — हर पायदान का अर्थ जानने के लिए देखें Guidance।

किसी विज़िटर के सेशनों की सूची

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

सेशन नवीनतम पहले के क्रम में लौटते हैं:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

पेजिनेशन

पेजिंग कर्सर-आधारित है। कोई page या offset पैरामीटर नहीं है: आपको जो nextCursor मिला उसे cursor के रूप में वापस भेजें, और जब तक hasMore सही है तब तक चलते रहें।

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

  do {
    const url = new URL(`https://api.tracio.ai/v1/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.nextCursor
  } while (cursor)

  return sessions
}

कर्सर को अपारदर्शी मानें — उसकी सामग्री एक कार्यान्वयन विवरण है और बदल सकती है। संपादित किया गया कर्सर 400 invalid_request और संदेश malformed cursor के साथ अस्वीकार कर दिया जाता है।

डिवाइस के तथ्य

User-Agent से लिए गए ब्राउज़र और OS के साथ-साथ, एक सेशन वह भी रखता है जो विज़िटर का ब्राउज़र मशीन के बारे में बताता है, हमारी ओर से साफ़ किया हुआ। विज़िट ऐसा डेटा न लाए तो हर फ़ील्ड अनुपस्थित रहता है, इसलिए हर एक को वैकल्पिक मानें।

ब्राउज़र एक्सटेंशन

extensions उन ब्राउज़र एक्सटेंशनों को सूचीबद्ध करता है जो विज़िट के दौरान पकड़े गए — Business और उससे ऊपर। हर प्रविष्टि एक ऑब्जेक्ट है:

कोई निष्कर्ष तभी बताया जाता है जब वह हमारी भरोसे की जाँचों में खरा उतरे — जो परिवेश हर जाँच पर "इंस्टॉल है" उत्तर देता है, या जो बैच बारह नामों से लंबा होता है, उसे अविश्वसनीय मानकर हटा दिया जाता है। इसलिए खाली या अनुपस्थित सूची का अर्थ है "ऐसा कुछ नहीं जिसकी हम पुष्टि कर सकें", न कि "कोई एक्सटेंशन इंस्टॉल नहीं है"। इसे प्रमाण की तरह पढ़ें, इन्वेंटरी की तरह नहीं।

एक सेशन प्राप्त करना

सबसे हालिया वाला:

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

यह एक सादा सेशन ऑब्जेक्ट लौटाता है — न कोई ऐरे, और न ही किसी एनवेलप में लिपटा हुआ। विंडो में बिना किसी सेशन वाला विज़िटर 404 not_found और no sessions for this visitor in the retention window लौटाता है।

या requestId से, वह पहचानकर्ता जो webhook पेलोड में भी आता है:

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

यहाँ visitorId वैकल्पिक है, पर जब वह आपको पता हो तब उसे भेजना लुकअप को उल्लेखनीय रूप से तेज़ बना देता है।

वेलोसिटी

वेलोसिटी इस प्रश्न का उत्तर देती है कि "यह विज़िटर हाल में कितना कुछ कर रहा है" — यही क्रेडेंशियल स्टफ़िंग, कार्ड टेस्टिंग और थोक साइनअप का आकार है।

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

window 1h, 24h या 7d स्वीकार करता है और डिफ़ॉल्ट रूप से 24h है। कोई भी अन्य मान 400 invalid_request और window must be one of: 1h, 24h, 7d के साथ अस्वीकार कर दिया जाता है।

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts उन अलग-अलग linkedId मानों की गिनती करता है जो आपने इस डिवाइस के लिए भेजे — देखें अकाउंट लिंकिंग। botEvents Business और उससे ऊपर है।

रिस्पॉन्स की परिपाटियाँ

अनुपस्थित फ़ील्ड का अर्थ है "कोई डेटा नहीं", कभी शून्य नहीं। बिना मान वाले फ़ील्ड 0, "" या null के रूप में भेजे जाने के बजाय पूरी तरह हटा दिए जाते हैं: बिलकुल नए विज़िटर के पास कोई matchConfidence नहीं होता, साफ़-सुथरी विज़िट के पास कोई antidetectScore या suspectScore नहीं होता। एकमात्र जान-बूझकर रखा गया अपवाद है bot.score, जो शून्य होने पर भी हमेशा मौजूद रहता है। फ़ील्ड सावधानी से पढ़ें।

पेलोड आपके प्लान पर निर्भर करता है। API पहुँच वाला हर प्लान बेस सेशन पाता है — पहचानकर्ता, टाइमस्टैम्प, URL, IP, user agent, ब्राउज़र, OS, डिवाइस, geo, network, bot, identification और decision। Pro इसमें identification.matchType, identification.matchConfidence, bot.type, bot.antidetectScore, gpu और network.proxyDetected जोड़ता है। Business और Enterprise extensions, geo.isp, network.asn, network.realIp, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo, spoofing, osEnvironment, screen, locale, clientHints और environment जोड़ते हैं। व्यक्ति-स्तर के फ़ील्ड (personId, reputation, linkedAccountsCount, linkedVisitorsCount) Business और Enterprise के लिए आरक्षित हैं और व्यक्ति परत सक्षम होते ही दिखाई देंगे — आज यह ऑब्ज़र्वेशन मोड में चलती है और ये फ़ील्ड नहीं भेजे जाते। Pro प्लान पर किसी Business फ़ील्ड की अनुपस्थिति कोई त्रुटि नहीं है।

सिग्नल-स्तर की आंतरिक बातें कभी नहीं लौटाई जातीं, किसी भी प्लान पर: अलग-अलग सिग्नल के नाम, उनके वज़न, किसी वर्डिक्ट के पीछे की थ्रेशोल्ड, कच्चे सिग्नल मान और स्कोर का विश्लेषण हमारी ओर ही रहते हैं। जिस स्कोर की उसके इनपुट में रिवर्स इंजीनियरिंग हो सके, वह बचाव के रूप में उपयोगी नहीं रह जाता।

त्रुटियाँ

हर विफलता एक ही एनवेलप का उपयोग करती है:

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

यह requestId विज़िट पहचानकर्ता नहीं है। दो अलग-अलग मान एक ही नाम साझा करते हैं: सेशन पेलोड के भीतर requestId विज़िट का UUID है, वही जो webhook पहुँचाता है; त्रुटि एनवेलप के भीतर यह प्रति HTTP कॉल बनाया गया 24-वर्ण का ट्रेस पहचानकर्ता है। यह ट्रेस पहचानकर्ता हर उत्तर पर X-Request-Id हेडर में भी वापस आता है, चाहे उत्तर सफल हो या न हो। सपोर्ट से संपर्क करते समय इसे साथ दें — इसी से हम आपकी ठीक वही कॉल ढूँढ़ते हैं।

जांचें एक निश्चित क्रम में चलती हैं — पहले कुंजी, फिर प्लान, फिर सीमाएँ — इसलिए गलत कुंजी वाला अनुरोध हमेशा पहले कुंजी की ही रिपोर्ट करता है, कभी कोटा की समस्या नहीं।

दो 401 स्थितियाँ जान-बूझकर अलग-अलग पढ़ी जाती हैं: missing Authorization: Bearer <secret key> का अर्थ है कि हेडर आया ही नहीं, जबकि invalid or revoked API key का अर्थ है कि वह आया और मेल नहीं खाया। 402 के साथ आता है Data API requires the Pro plan or higher।

रेट लिमिट और कोटा

हर प्रमाणित उत्तर आपकी वर्तमान स्थिति साथ लाता है:

• छोटे बर्स्ट की अनुमति है: प्रति-सेकंड सीमा एक टोकन बकेट है जो मना करना शुरू करने से पहले सतत दर से तीन गुना तक सह लेती है।
• प्रति-सेकंड दर पार करने के कारण अस्वीकार किया गया अनुरोध दैनिक कोटा नहीं खर्च करता, इसलिए कोई बर्स्ट दिन भर का बजट नहीं खा सकता।
• Data API की सीमाएँ पहचान ट्रैफ़िक से अलग गिनी जाती हैं। अपना ही इतिहास पढ़ने पर वे पहचानें कभी खर्च नहीं होतीं जिनके लिए आप भुगतान कर रहे हैं।

अगले कदम

• Webhooks — हर पहचान को घटित होते ही प्राप्त करें
• अकाउंट लिंकिंग — अपना अकाउंट id किसी डिवाइस से जोड़ें
• बॉट डिटेक्शन — बॉट वर्डिक्ट कैसे बनता है
• गोपनीयता और GDPR — डेटा-विषय अनुरोधों को संभालना