Data API

The Data API (formerly documented here as the Server API) lets your backend read the identification data TRACIO has already collected for your workspace: a visitor's history, individual sessions, and short-window velocity counters. A few routes also write — account records, custom fields and list entries — so your backend can enrich what TRACIO knows.

It complements webhooks rather than replacing them:

Both surfaces are available from the Pro plan and above.

Base URL

https://api.tracio.ai/v2

This is a different host from the browser endpoint (edge.tracio.ai) and from the dashboard (app.tracio.ai). All three are separate: the browser talks to the edge with your public key, your backend talks to the Data API with your secret key.

Migrating from v1

The /v1 routes have been removed. Use /v2: the routes are the same, and every JSON key and query parameter is in snake_case (visitor_id, risk_score, min_risk_score). Keys inside your own fields and labels dictionaries are your data and keep their original spelling. The JavaScript SDK keeps its camelCase interface.

Authentication

Every request carries your secret key as a bearer token:

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

The Data API is server-to-server only. CORS headers are deliberately not returned, so a browser cannot call it — that is what keeps your secret key out of client-side code. Never ship the secret key to the browser.

Getting a secret key

Create it in the dashboard under API Keys, choosing the secret type.

• The full key is shown exactly once, at creation. Only a hash is stored on our side, so a lost key cannot be recovered — rotate it instead.
• A secret key looks like tracio_sk_ followed by 43 characters, 53 in total. The dashboard lists it by its first few characters so you can tell keys apart.
• Secret keys require the Pro plan or higher; the public key used by the browser agent is a separate, non-secret 40-character value.
• A key is bound to an environment: a production key does not see a visitor from staging — the response is 404, exactly as for data that does not exist.

Rotating a secret key

Rotating issues a new key and keeps the old one working for 7 days, so you can roll it out without downtime. Deploy the new key, confirm traffic has moved, and let the old one expire. Public keys are not rotatable — they are not secrets and are visible in your page source by design.

Endpoints

The same key and host also serve the decision APIs, all in snake_case:

Their outcomes also reach you as webhook events: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked and affiliate_threshold_crossed.

A trailing slash is accepted and ignored. An unknown path or a wrong method returns the same JSON error envelope as everything else, never an HTML or plain-text page.

The time window

Every read is bounded by a time window, controlled by two optional query parameters:

• A bare date as to includes that whole day.
• Anything else is rejected with 400 invalid_request and the message time must be YYYY-MM-DD or RFC3339.
• When you pass neither, the window is your plan's full retention period, ending now.
• A window reaching further back than your plan allows is silently clamped rather than rejected. The window actually used is always reported back in meta, so check meta.from and meta.to instead of assuming your request was honored verbatim.

Look up a visitor

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

The response carries the aggregate history and embeds the latest session, so the common case needs one request rather than two:

{
  "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"
  }
}

A visitor with no data inside the retention window returns 404 not_found with the message visitor not found in the retention window — that is not an error in your integration, it means the visitor is new or has aged out.

Verdict fields

The session carries two verdicts, and they answer different questions — whether the client was automated, and what the risk engine concluded overall:

bot.score and decision.risk_score both run 0..100. On Business and above, guidance turns them into per-scenario advice on the ladder allow → challenge → review → deny — see Guidance for what each rung means. Values and scales match the v3 webhook body for the same visit, and guidance is computed by the same rules.

List a visitor's sessions

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

Sessions come back newest first:

{
  "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"
  }
}

Pagination

Paging is cursor-based. There is no page or offset parameter: pass the next_cursor you received back as cursor, and keep going while has_more is true. The last page may not include next_cursor at all, so do not make that field required.

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
}

Treat the cursor as opaque — its contents are an implementation detail and may change. A cursor that has been edited is rejected with 400 invalid_request and the message malformed cursor.

Device facts

Alongside the browser and OS taken from the User-Agent, a session carries what the visitor's browser reports about the machine, sanitized on our side. Every field is absent when the visit carried no such data, so treat each as optional.

Browser extensions

extensions lists the browser extensions detected during the visit — Pro and above. Each entry is an object:

A finding is reported only after it has passed our trust checks — an environment that answers "installed" to every probe, or a batch longer than twelve names, is discarded as unreliable. An empty or missing list therefore means "nothing we could confirm", not "no extensions installed". Read it as evidence, not as an inventory.

Custom fields

fields holds the custom key-value pairs your integration attached to the visit — an order reference, a plan name, a payment outcome. Keys and values are always strings: a number or boolean you attached comes back in its text form. Like the rest of the session, it is available on every plan with API access (Pro and above), and it is absent when the visit carries no fields.

fields is read live on every request, not copied at visit time. Fields attached after the visit (see Attaching fields after the visit) show up here too, so for the same visit fields may contain more than the webhook delivered.

Do not put personal data such as names, email addresses or phone numbers into custom fields — attach a reference that your own systems can resolve instead, and send who the account is as an account record (below).

Account record

account is your record for the account behind the visit — what you last sent for that account_id through POST /v2/accounts/metadata:

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

The record is read live on every request, so a rename shows up on old visits too: the block describes the account as it is now, not as it was at visit time. It is available on every plan with API access (Pro and above). Labels you sent with the record are not returned.

The block is absent when the visit has no linked account, when there is no record for it (or you cleared it by sending empty values), and — rarely — when the record could not be read: the session is still returned in full rather than failing the request, so treat a missing block as "unknown", not as "this account has no email". Webhooks do not carry this block.

Fetch a single session

The most recent one:

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

This returns a bare session object — not an array, and not wrapped in an envelope. A visitor with no sessions in the window returns 404 not_found with no sessions for this visitor in the retention window.

Or by request_id, the identifier that also appears in the webhook payload:

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

visitor_id is optional here, but passing it when you know it makes the lookup markedly faster.

identification.drift_score — the smoothed behavior score the account-takeover verdict was made on, Business and above — is returned only by this single-session read. Behavior drift is measured during the visit, after the initial identification, so the list and latest-session routes omit it. A visit whose behavior was never judged has no drift_score. The same value reaches you through the account_takeover webhook.

Which answer you get for a corrected visit

A visit can be delivered more than once by webhook: primary first, then late or correction as slower signals and behavioral evidence arrive — and a later phase can overturn the earlier verdict. The Data API answers from the primary record. Later phases are not merged back into it, so for a corrected visit the last webhook is the newer answer. If you act minutes after the visit, prefer the phase you received last over a fresh read here.

One thing runs the other way: once the account-takeover detector has fired for a visit, guidance here reflects it, while identification webhook bodies of the same visit do not carry that axis — it rides the dedicated account_takeover delivery.

Velocity

Velocity answers "how much has this visitor been doing lately" — the shape of credential stuffing, card testing and bulk signups.

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

window accepts 1h, 24h or 7d and defaults to 24h. Any other value is rejected with 400 invalid_request and window must be one of: 1h, 24h, 7d.

{
  "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 counts the distinct linkedId values you sent for this device — see Account Linking. bot_events is Business and above; the key is absent on Pro.

Account metadata

TRACIO knows your accounts only by the ID your site passes as linkedId — an opaque string like usr_8412. Send the human labels once, and every dashboard screen that shows that account shows the name or email instead of the raw ID, and the session object returns them in its account block. Nothing here affects detection or scoring; it is a display layer.

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 }

• This is the place for personal data about an account — not fields. An email or a name sent here lives only in your workspace's account record: it is not stored per visit, not written into the page, and one send updates every visit of that account.
• Scope is the key's workspace and environment. A staging key never overwrites what a production key wrote for the same account ID.
• Every send is a full overwrite, not a patch. Fields you omit are stored empty — send the complete record each time. That is also how you clear a value.
• Unknown fields are rejected with 400 invalid_request, and one bad entry rejects the whole batch — the error names its position. Duplicate account IDs in one batch are fine: the last one wins.

Limits: 1000 accounts per request, 1 MiB body, account_id ≤ 256 characters, email ≤ 320, display_name ≤ 256, at most 16 labels with keys ≤ 64 and values ≤ 256 characters.

Attaching fields after the visit

The browser can only send what the page knows at render time — an order ID, never the outcome of a payment check or anything else that resolves later. This route fills that gap: find the visit by a field it already carries, and attach more fields to it server-side.

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 finds the visit by a field it already has, not by request_id, within your key's workspace and environment.
• The search window is 24 hours. An older visit returns 404 not_found — write the field soon after the outcome resolves.
• updated counts distinct visits. It goes above 1 only when your match hits more than one visit — a key/value pair that is not unique to one order or cart. A match that hits more than 100 events is refused with 400 invalid_request rather than applied to an arbitrary subset.
• Fields written here show up in the dashboard tagged server, and take priority over a value with the same key written by the browser.
• No match is 404 not_found, not an empty 200.

Limits match the browser channel: 50 fields per call, keys ≤ 40 bytes, values ≤ 500 bytes — bytes, not characters — key charset A-Za-z0-9_.:-, 1 MiB body.

Deleting fields

Erases custom fields — never the visit itself. Use it for values you no longer need attached to a visit, such as an order total. Webhooks already sent and exports already taken are not changed.

# 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 and match are mutually exclusive — sending both, or neither, is 400 invalid_request. match uses the same 24-hour window and the same 100-event ceiling as attaching.
• deleted counts the fields removed from the visit (by request_id) or the visits the field was removed from (by match).
• Calling it again once nothing is left returns 404 not_found.
• A field the browser sends again after your delete comes back. When Tracio.load().get({ fields }) (and so the SDK) passes fields after the visit's first request has already left, the page sends them in a separate follow-up request — up to 3 per visit, while the visit's session is still alive (minutes). Such a follow-up that arrives after your delete writes the field again. The window is the life of the browser session, not of the visit record: delete fields once the visitor has left the page, not while it is still open.

Workspace lists

The same lists your operators manage in the dashboard, reachable from your own back office. A list's type is its action on a matching visit — block, manual_review, challenge, allow — and its mode decides whether the action is applied: observe only counts matches, enforce applies it to guidance (the list axis). Lists and their mode are created in the dashboard; the Data API reads lists and adds and removes entries.

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"
}

Remove an entry with the same body at POST /v2/lists/{list_id}/entries/delete; the answer is { "removed": true, "propagation": "immediate" }.

• value_type is what the value is matched against: linked_id, visitor_id, device_id, ip, cidr or country. A value that does not parse for its type is 400 invalid_request.
• When several lists match, the most specific type decides — linked_id → visitor_id → device_id → ip → cidr → country — and within it the strictest action wins.
• ttl_minutes is optional. Omitted, the list's default TTL applies; with none, the entry never expires (expires_at is null). Re-adding an entry renews it.
• propagation says when the change is live: immediate, or ttl — within about five minutes.
• Deleting a value that is not there is 200 with removed: false; 404 is reserved for an unknown list.

Response conventions

A missing field means "no data", never zero. Fields with no value are omitted entirely rather than sent as 0, "" or null: a brand-new visitor has no match_confidence, a clean visit has no antidetect_score or suspect_score. The one deliberate exception is bot.score, which is always present even when it is zero. Read fields defensively.

The payload depends on your plan. API access starts at Pro, and Pro gets the base session — identifiers, timestamp, URL, IP, user agent, browser, OS, device, geo, network, bot, identification and decision — together with identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields and account. Business and Enterprise add 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 and environment. The person-level fields (person_id, reputation, linked_accounts_count, linked_visitors_count) are reserved for Business and Enterprise and will appear once the person layer is enabled — today it runs in observation mode and these fields are not delivered. Absence of a Business field on a Pro plan is not an error.

Signal-level internals are never returned, on any plan: individual signal names, their weights, the thresholds behind a verdict, raw signal values, and score breakdowns stay on our side. A score that can be reverse-engineered into its inputs stops being useful as a defence.

Errors

Every failure uses one envelope:

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

This request_id is not the visit identifier. Two different values share the name: inside a session payload request_id is the UUID of the visit, the same one the webhook delivers; inside an error envelope it is a 24-character trace identifier minted per HTTP call. The trace identifier also comes back in the X-Request-Id header on every response, successful or not. Include it when you contact support — it is how we find your exact call.

Checks run in a fixed order — key, then plan, then limits — so a request with a bad key always reports the key first, never a quota problem. Data from another workspace is indistinguishable from data that does not exist: it yields 404, not 403.

Two 401 cases read differently on purpose: missing Authorization: Bearer <secret key> means the header never arrived, while invalid or revoked API key means it arrived and did not match. 402 carries Data API requires the Pro plan or higher.

Retry 429 and 503 with a growing pause; retrying other 4xx is pointless — they mean the request itself needs fixing.

Rate limits and quotas

Responses for which the key has been recognized carry your current standing (401 and 402 responses do not, and Enterprise, with no daily quota, gets no quota headers):

• Short bursts are allowed: the per-second limit is a token bucket that tolerates up to three times the sustained rate before it starts refusing.
• A request refused for exceeding the per-second rate does not consume daily quota, so a burst cannot eat the day's budget.
• Data API limits are counted separately from identification traffic. Reading your own history never spends the identifications you are paying for.

Next steps

• Webhooks — receive each identification as it happens
• Account Linking — attach your own account id to a device
• Bot Detection — how the bot verdict is produced
• Privacy & GDPR — handling data-subject requests