InferTrail API

Detect abuse of your AI product from request metadata. InferTrail never needs prompt or response content, and rejects requests that include it.

Base URL https://api.infertrail.com · Version v1

Quickstart

InferTrail scores each request to your AI product for abuse risk, using only metadata about the request: who sent it, from where, how fast, and what it cost. You never send prompts or responses.

  1. Create a secret key. In the InferTrail dashboard, open API keys and create a secret key. It starts with it_live_ and is shown once.
  2. Score before you serve. From your backend, call POST /v1/score with your identifier for the user's account and what you know about the request. If the answer says blocked: true, refuse the request.
  3. Record what happened. When the model call finishes, send its tokens and cost to POST /v1/events/post-call, using the same event_id.
  4. Tell InferTrail what you learn. When you confirm an account was abusive or legitimate, send a label. Labels are your ground truth in the dashboard.
curl -X POST https://api.infertrail.com/v1/score \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acct_42", "event_id": "req_8f3a", "request": {"ip": "203.0.113.7", "model_requested": "gpt-4o-mini"}}'

New accounts are scored by cold-start rules (shadow_mode: true). Once an account has enough history, the trained model scores it and baseline_ready becomes true.

Authentication

Send your secret key as a bearer token on every request:

Authorization: Bearer it_live_…

Keep secret keys on your servers. Never put one in a browser, mobile app or public repository. Each key belongs to one workspace, and every request only reads and writes that workspace's data.

The browser sensor is the one exception: POST /v1/sensor/collect runs in the browser and takes a publishable key (pk_live_…) in its body. A publishable key only works from the origins you allow for it, and cannot read or write anything else.

You can rotate or revoke a key in the dashboard. A revoked key stops working everywhere within a minute or two.

Idempotency and retries

Give each event a stable event_id: your request ID works well. InferTrail records an event once per workspace, event type and ID. If you send the same ID again, you get the original answer back with duplicate: true, even if the body changed. To get a fresh verdict, use a new ID.

This makes retries safe. When a request fails with a 5xx status or times out, retry it with the same event_id, waiting a little longer each time.

When you omit event_id on /v1/score or /v1/events/post-call, InferTrail generates one and returns it. A retry without an ID is recorded as a new event. Batch ingestion always requires IDs.

Errors

Errors return a JSON body with a short reason:

{"error": "Invalid metadata request."}
400The body is malformed, too large, or contains prompt or response content. Fix the request; retrying it unchanged won't help.
401The key is missing, unknown, revoked, or not a secret key.
403The key may not use this route.
404Nothing with that identifier belongs to your workspace.
409Another request with the same idempotency key is still in progress.
413A batch exceeds its size limit.
429The key is sending too fast. Wait briefly and retry.
503, 504InferTrail could not finish. Retry with the same event_id.

Scoring never fails closed. If scoring itself fails, POST /v1/score still answers 200 with score: 0, tier: "low" and the reason scoring_unavailable, so an outage on our side doesn't block your users. Manual blocks and spend caps still apply.

Limits

  • Request bodies: at most 1 MiB. The known fields of one event: at most 64 KiB.
  • Batch ingestion: 1 to 100 events and at most 512 KiB per request.
  • IDs (event_id and others): at most 256 characters.
  • event_time in a batch: at most seven days ago and one minute ahead. Leave it out to use the time InferTrail received the event.
  • Token counts, latency and costs: zero or more. Leave a token count out, or send null, when you don't know it; it is not counted as zero. If you leave out the cost, InferTrail estimates it from the tokens and marks it as an estimate.

Metadata only

InferTrail works from metadata and never needs what users wrote or what the model answered. Any request containing a field named prompt, prompt_text, prompt_text_to_fingerprint, response, response_text, completion_text, messages, raw_request or raw_response, at any depth, is rejected with 400.

Send only what you need: an identifier for the account rather than an email address where you can, and never credentials or payment details.

Scoring

Score each request before you serve it, and record what happened after.

POST /v1/score

Score a request

Call before you serve a model request. Returns a risk score and whether to refuse the request. The answer comes from InferTrail's edge, typically within milliseconds. If scoring itself fails you still get HTTP 200 with score 0 and the reason scoring_unavailable, so a failure never blocks your users; blocks and spend caps still apply.

Request body

FieldTypeDescription
account_id requiredstringYour identifier for the end user's account. Required and not blank.
event_idstring | nullYour idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.
session_idstring | nullYour identifier for the user's session, if you have one.
accountobject | nullWhat you know about the account. Only these three keys are accepted.
account.subscription_tierstring | nullYour name for the account's subscription tier.
account.first_seenstring | nullWhen the account was created, as an RFC 3339 timestamp with a time zone.
account.contextobject | nullFacts you attest about the account. A null, empty or unrecognized value changes nothing; recognized values overlay what InferTrail already stores.
account.context.plan_typestring | nullThe account's plan. Recognized values: paid, unpaid, trial, free (any case). Other values are ignored.
account.context.has_payment_methodboolean | nullWhether a payment method is on file.
account.context.email_verifiedboolean | nullWhether the account's email address is verified.
account.context.identity_verifiedboolean | nullWhether you have verified the account holder's identity.
account.context.prior_chargebackboolean | nullWhether the account has had a chargeback.
account.context.billing_delinquentboolean | nullWhether the account is behind on payments.
account.context.trust_labelstring | nullYour trust assertion. Recognized values: vip, allowlisted, allowlist, trusted (any case).
requestobject | nullMetadata about this request. Never include prompt or response text.
request.ipstring | nullThe end user's IP address.
request.ip_hashstring | nullYour own hash of the end user's IP address, used only when ip is absent. At most 128 characters.
request.asninteger | nullThe autonomous system number of the end user's network.
request.ip_countrystring | nullTwo-letter country code of the end user's IP address. Malformed values are dropped.
request.user_agentstring | nullThe end user's User-Agent header.
request.model_requestedstring | nullThe model the user asked for.
request.estimated_prompt_tokensinteger | nullYour estimate of the prompt's size in tokens.
request.sensor_tokenstring | nullA token from POST /v1/sensor/collect. Accepted, but not yet used in the score; see signals_fused.
request.session_signalsobject | nullBehavioral timing you observed in the session.
request.session_signals.ms_since_last_requestinteger | nullMilliseconds since this session's previous request.
request.session_signals.ms_since_page_loadinteger | nullMilliseconds since the page that sent the request loaded.
request.session_signals.interaction_events_countinteger | nullNumber of user interactions (clicks, keys, scrolls) seen in the session.
request.session_signals.ms_since_signupinteger | nullMilliseconds since the account signed up.
request.session_signals.is_first_request_in_sessionboolean | nullWhether this is the session's first request.
request.clientobject | nullClient-side automation signals.
request.client.webdriverboolean | nullWhether the browser reported navigator.webdriver.

Example request

curl -X POST https://api.infertrail.com/v1/score \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acct_42",
  "event_id": "req_8f3a",
  "session_id": "sess_19",
  "account": {
    "subscription_tier": "pro",
    "first_seen": "2026-10-02T09:15:00Z",
    "context": {
      "plan_type": "paid",
      "email_verified": true
    }
  },
  "request": {
    "ip": "203.0.113.7",
    "user_agent": "Mozilla/5.0",
    "model_requested": "gpt-4o-mini",
    "estimated_prompt_tokens": 850
  }
}'

Response 200

The score.

FieldTypeDescription
event_idstringThe event's ID: yours, or one InferTrail generated when you sent none.
score requirednumberRisk from 0 (benign) to 1 (abusive).
tier requiredstringRisk band of the score: below 0.4 is low, 0.4 up to 0.7 is medium, 0.7 and above is high. One of low, medium, high.
reasons requiredstring[]Machine-readable reasons, most important first. scoring_unavailable means scoring failed and the answer is a safe default.
blocked requiredbooleanWhether you should refuse the request: a manual block or an exceeded spend cap applies.
shadow_mode requiredbooleanTrue while the account has too little history for the trained model; the score then comes from cold-start rules.
baseline_ready requiredbooleanTrue once the account's history is sufficient for the trained model.
deep_mode_active requiredbooleanAlways false. InferTrail never inspects prompt content.
signals_fused requiredbooleanCurrently always false: browser sensor signals are not yet combined into scores. Check a sensor token with POST /v1/sensor/verify.
duplicatebooleanPresent and true when this event_id was already scored; the original answer is returned unchanged.
algorithmstringName of the scoring method that produced the score.
algorithm_versionstringVersion of that method.
service_versionstringVersion of the scoring service.
scorer_versionstringVersion of the full scorer, including its rules.
groupingobjectEvidence from your workspace's group rules, when any matched. See your dashboard's scoring settings.
{
  "event_id": "req_8f3a",
  "score": 0.12,
  "tier": "low",
  "reasons": [],
  "blocked": false,
  "shadow_mode": false,
  "baseline_ready": true,
  "deep_mode_active": false,
  "signals_fused": false
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
405Wrong HTTP method; the Allow header names the right one.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

POST /v1/events/post-call

Record a completed call

Call after a model request finishes, with its usage and cost. The event is queued durably before the answer; pricing, spend totals and caps are applied right after. Unknown token counts stay unknown rather than counting as zero.

Request body

FieldTypeDescription
account_id requiredstringThe account that made the call. Required and not blank.
event_idstringYour idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.
session_idstring | nullYour identifier for the user's session.
modelstring | nullThe model that served the call.
prompt_tokensinteger | nullPrompt tokens used. Null or absent means unknown, not zero.
completion_tokensinteger | nullCompletion tokens used. Null or absent means unknown, not zero.
latency_msinteger | nullHow long the call took, in milliseconds.
inference_cost_usdnumber | nullWhat the call cost you, in US dollars. When omitted, InferTrail estimates it from tokens and marks the estimate.
telemetryobjectTiming of the completed model call.
telemetry.version requiredinteger1, or 2 to include model_id and stream. One of 1, 2.
telemetry.source_id requiredstringYour identifier for the system that served the call, at most 128 bytes.
telemetry.model_family requiredstringSize class of the model. One of small, medium, large, reasoning.
telemetry.model_idstringVersion 2 only: the exact model identifier, at most 256 bytes.
telemetry.streamboolean | nullVersion 2 only: whether the response was streamed.
telemetry.status requiredintegerHTTP status your model call returned.
telemetry.start_ts requirednumberWhen the call started, in Unix seconds.
telemetry.end_ts requirednumberWhen the call ended, in Unix seconds: not before start_ts, at most a day after it and not in the future.

Example request

curl -X POST https://api.infertrail.com/v1/events/post-call \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acct_42",
  "event_id": "req_8f3a",
  "model": "gpt-4o-mini",
  "prompt_tokens": 850,
  "completion_tokens": 212,
  "latency_ms": 1430,
  "inference_cost_usd": 0.00026
}'

Response 200

Accepted for processing.

FieldTypeDescription
ok requiredbooleanAlways true on success.
accepted requiredbooleanThe event is durably queued. Pricing and spend caps are applied after the answer.
event_id requiredstringThe event's ID: yours, or one InferTrail generated.
{
  "ok": true,
  "accepted": true,
  "event_id": "req_8f3a"
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
405Wrong HTTP method; the Allow header names the right one.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

POST /v1/identity

Record an identity event

Record a login, signup or similar event for an account, so its network and device history inform later scores.

Request body

FieldTypeDescription
account_id requiredstringThe account the identity event belongs to.
event_idstringYour idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.
session_idstring | nullYour identifier for the user's session.
event_typestring | nullWhat happened, such as login, signup or password_reset.
ipstring | nullThe user's IP address.
ip_hashstring | nullYour own hash of the IP address, used only when ip is absent.
asninteger | nullAutonomous system number of the user's network.
ip_countrystring | nullTwo-letter country code of the IP address.
user_agentstring | nullThe user's User-Agent header.
registration_idstring | nullThe registration_id from POST /v1/registrations/score, to link the signup to this account.

Example request

curl -X POST https://api.infertrail.com/v1/identity \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acct_42",
  "event_id": "login_771",
  "event_type": "login",
  "ip": "203.0.113.7",
  "user_agent": "Mozilla/5.0"
}'

Response 200

Recorded.

FieldTypeDescription
ok requiredbooleanAlways true on success.
duplicatebooleanPresent and true when this event_id was already recorded.
{
  "ok": true
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
405Wrong HTTP method; the Allow header names the right one.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

POST /v1/labels

Label an account

Tell InferTrail what an account turned out to be. Labels are your ground truth: they show in the dashboard and carry over to signups linked to the account.

Request body

FieldTypeDescription
account_id requiredstringThe account to label.
label requiredstringYour verdict. One of fraud, legitimate.
notesstringFree-text notes for your team. Do not include personal data you don't need.
event_idstringYour idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.

Example request

curl -X POST https://api.infertrail.com/v1/labels \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acct_42",
  "label": "fraud",
  "event_id": "label_acct_42_1"
}'

Response 200

Recorded.

FieldTypeDescription
ok requiredbooleanAlways true on success.
duplicatebooleanPresent and true when this event_id was already recorded.
{
  "ok": true
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
405Wrong HTTP method; the Allow header names the right one.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

POST /v1/accounts/{account_id}/context

Set account context

Store facts about an account, such as its plan or whether its email is verified, without sending them on every score. Facts you send inline with POST /v1/score overlay these.

Parameters

NameInDescription
account_id requiredpath, stringYour identifier for the end user's account, URL-encoded.

Request body

FieldTypeDescription
plan_typestring | nullThe account's plan. Recognized values: paid, unpaid, trial, free (any case). Other values are ignored.
has_payment_methodboolean | nullWhether a payment method is on file.
email_verifiedboolean | nullWhether the account's email address is verified.
identity_verifiedboolean | nullWhether you have verified the account holder's identity.
prior_chargebackboolean | nullWhether the account has had a chargeback.
billing_delinquentboolean | nullWhether the account is behind on payments.
trust_labelstring | nullYour trust assertion. Recognized values: vip, allowlisted, allowlist, trusted (any case).

Example request

curl -X POST https://api.infertrail.com/v1/accounts/{account_id}/context \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "plan_type": "trial",
  "has_payment_method": false,
  "email_verified": true
}'

Response 200

Recorded.

FieldTypeDescription
ok requiredbooleanAlways true on success.
duplicatebooleanPresent and true when this event_id was already recorded.
{
  "ok": true
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
405Wrong HTTP method; the Allow header names the right one.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

Batch ingestion

Send usage and identity events in batches from your backend, and check their processing.

POST /v1/ingress/events

Send events in a batch

Send 1 to 100 post-call or identity events in one request from your backend. HTTP 202 means every event is durably queued, not yet processed; each gets a receipt you can check. If the answer is 503, resend the same batch with the same event IDs.

Request body

FieldTypeDescription
events requiredobject[]1 to 100 events. 1 to 100 items.
events[].event_id requiredstringRequired idempotency key, at most 256 characters, unique within the request.
events[].type requiredstringThe event's kind. One of post_call, identity.
events[].event_timestringWhen the event happened, at most seven days ago and one minute ahead. Defaults to the time InferTrail received it.
events[].data requiredobjectThe event: the fields of POST /v1/events/post-call for post_call, or of POST /v1/identity for identity. A data.event_id, if sent, must equal the envelope's.

Example request

curl -X POST https://api.infertrail.com/v1/ingress/events \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "event_id": "call_1001",
      "type": "post_call",
      "data": {
        "account_id": "acct_42",
        "model": "gpt-4o-mini",
        "prompt_tokens": 100,
        "completion_tokens": 50,
        "inference_cost_usd": 0.00004
      }
    },
    {
      "event_id": "login_772",
      "type": "identity",
      "event_time": "2026-11-18T08:00:00Z",
      "data": {
        "account_id": "acct_42",
        "event_type": "login",
        "ip": "203.0.113.7"
      }
    }
  ]
}'

Response 202

Queued.

FieldTypeDescription
acceptancestringAlways queue.
acceptedintegerNumber of events queued.
processingstringAlways asynchronous.
eventsobject[]One receipt per event, in request order.
events[].event_idstringThe event's ID.
events[].receipt_idstringThe receipt to check.
events[].statusstringAlways queued.
events[].status_urlstringPath of the receipt.
{
  "acceptance": "queue",
  "accepted": 1,
  "processing": "asynchronous",
  "events": [
    {
      "event_id": "call_1001",
      "receipt_id": "rcpt_5c1d",
      "status": "queued",
      "status_url": "/v1/ingress/receipts/rcpt_5c1d"
    }
  ]
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
405Wrong HTTP method; the Allow header names the right one.
413The batch exceeds its size limit.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

GET /v1/ingress/receipts/{receipt_id}

Check a receipt

How a queued event is doing. A brand-new receipt can return 404 for a moment until processing records it.

Parameters

NameInDescription
receipt_id requiredpath, stringThe receipt_id from the batch answer.

Example request

curl -X GET https://api.infertrail.com/v1/ingress/receipts/{receipt_id} \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

The receipt.

FieldTypeDescription
receipt_idstringThe receipt's ID.
event_idstringThe event's ID.
typestringThe event's kind.
event_timestringWhen the event happened.
received_atstringWhen InferTrail received it.
status requiredstringqueued while waiting, completed once processed, conflict if the event ID was reused with different data (the original is kept), or failed after the queue's retries ran out. One of queued, completed, conflict, failed.
completed_atstringWhen processing finished.
errorstringWhy processing did not complete.
{
  "receipt_id": "rcpt_5c1d",
  "event_id": "call_1001",
  "type": "post_call",
  "status": "completed",
  "completed_at": "2026-11-18T08:00:01Z"
}

Errors

401The API key is missing, unknown, revoked, or not a secret key.
403The key may not use this route.
404Nothing with that identifier belongs to your workspace.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.
504The request did not finish in time. Retry with the same idempotency key.

GET /v1/ingress/events/{event_id}

Check an event

The same status as a receipt, found by your event ID.

Parameters

NameInDescription
event_id requiredpath, stringYour event ID.

Example request

curl -X GET https://api.infertrail.com/v1/ingress/events/{event_id} \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

The event's status.

FieldTypeDescription
receipt_idstringThe receipt's ID.
event_idstringThe event's ID.
typestringThe event's kind.
event_timestringWhen the event happened.
received_atstringWhen InferTrail received it.
status requiredstringqueued while waiting, completed once processed, conflict if the event ID was reused with different data (the original is kept), or failed after the queue's retries ran out. One of queued, completed, conflict, failed.
completed_atstringWhen processing finished.
errorstringWhy processing did not complete.

Errors

401The API key is missing, unknown, revoked, or not a secret key.
403The key may not use this route.
404Nothing with that identifier belongs to your workspace.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.
504The request did not finish in time. Retry with the same idempotency key.

GET /v1/ingress/status

Ingestion health

Counts of your recently processed events by outcome, and the latest ones.

Example request

curl -X GET https://api.infertrail.com/v1/ingress/status \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

Recent outcomes.

FieldTypeDescription
window_seconds requiredintegerHow far back the counts reach.
counts requiredobject
counts.completedintegerProcessed.
counts.conflictintegerRejected for reusing an event ID with different data.
counts.failedintegerFailed after retries.
recent requiredobject[]The latest events.
recent[].receipt_idstringThe receipt's ID.
recent[].event_idstringThe event's ID.
recent[].typestringThe event's kind.
recent[].event_timestringWhen the event happened.
recent[].received_atstringWhen InferTrail received it.
recent[].status requiredstringqueued while waiting, completed once processed, conflict if the event ID was reused with different data (the original is kept), or failed after the queue's retries ran out. One of queued, completed, conflict, failed.
recent[].completed_atstringWhen processing finished.
recent[].errorstringWhy processing did not complete.

Errors

401The API key is missing, unknown, revoked, or not a secret key.
403The key may not use this route.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.
504The request did not finish in time. Retry with the same idempotency key.

Accounts

Read scores, labels and usage for your accounts.

GET /v1/accounts

List accounts

Your accounts with their latest score, label and spend, one page at a time.

Parameters

NameInDescription
sortquery, stringWhat to sort by. One of score, last_seen, first_seen, requests, spend. Default score.
orderquery, stringSort direction. One of asc, desc. Default desc.
labelquery, stringOnly accounts with this label. One of fraud, legitimate, unlabeled.
tierquery, stringOnly accounts whose latest tier is this. One of low, medium, high.
min_scorequery, numberOnly accounts whose latest score is at least this.
windowquery, stringHow far back usage totals reach, counted from the start of the current hour. One of 1h, 1d, 7d, 30d. Default 30d.
limitquery, integerPage size. Values above 200 are capped at 200. Default 50.
offsetquery, integerNumber of entries to skip. Default 0.

Example request

curl -X GET https://api.infertrail.com/v1/accounts \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

A page of accounts.

FieldTypeDescription
accounts requiredobject[]The page.
accounts[].account_id requiredstringYour account identifier.
accounts[].first_seen requiredstringWhen InferTrail first saw the account.
accounts[].last_seen requiredstringWhen InferTrail last saw activity.
accounts[].subscription_tier requiredstring | nullThe subscription tier you reported.
accounts[].request_count requiredintegerScored requests for the account.
accounts[].last_label requiredstring | nullYour most recent label. One of fraud, legitimate.
accounts[].last_label_at requiredstring | nullWhen you labelled the account.
accounts[].latest_score requirednumber | nullThe most recent score.
accounts[].latest_tier requiredstring | nullThe most recent tier. One of low, medium, high.
accounts[].scored_at requiredstring | nullWhen the most recent score was given.
accounts[].inference_cost_usd requirednumberSpend in the window, in US dollars.
total requiredintegerAccounts matching the filters.
limit requiredintegerThe page size used.
offset requiredintegerThe offset used.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

GET /v1/accounts/{account_id}

Get an account

One account's latest score and its usage in the window, including which models it used.

Parameters

NameInDescription
account_id requiredpath, stringYour identifier for the end user's account, URL-encoded.
windowquery, stringHow far back usage totals reach, counted from the start of the current hour. One of 1h, 1d, 7d, 30d. Default 30d.

Example request

curl -X GET https://api.infertrail.com/v1/accounts/{account_id} \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

The account.

FieldTypeDescription
account_id requiredstringYour account identifier.
first_seen requiredstringWhen InferTrail first saw the account.
last_seen requiredstringWhen it was last active.
subscription_tier requiredstringThe subscription tier you reported.
request_count requiredintegerScored requests.
latest_score requiredobject
latest_score.score requirednumberThe score.
latest_score.tier requiredstringRisk band of the score: below 0.4 is low, 0.4 up to 0.7 is medium, 0.7 and above is high. One of low, medium, high.
latest_score.reasons requiredstring[] | nullIts reasons.
latest_score.received_at requiredstringWhen it was given.
latest_score.shadow_mode requiredbooleanWhether it came from cold-start rules.
latest_score.deep_mode_active requiredbooleanAlways false.
window requiredobjectUsage in the window.
window.events requiredintegerCompleted calls.
window.prompt_tokens requiredintegerPrompt tokens.
window.completion_tokens requiredintegerCompletion tokens.
window.inference_cost_usd requirednumberSpend in US dollars.
model_mix requiredobject[]Calls per model in the window.
model_mix[].model requiredstringModel name.
model_mix[].count requiredintegerCalls.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
404Nothing with that identifier belongs to your workspace.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

GET /v1/accounts/{account_id}/scores

List an account's scores

The account's score history, newest first.

Parameters

NameInDescription
account_id requiredpath, stringYour identifier for the end user's account, URL-encoded.
limitquery, integerPage size. Values above 200 are capped at 200. Default 50.
offsetquery, integerNumber of entries to skip. Default 0.

Example request

curl -X GET https://api.infertrail.com/v1/accounts/{account_id}/scores \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

A page of scores.

FieldTypeDescription
scores requiredobject[]The page.
scores[].id requiredintegerA stable numeric ID for this entry.
scores[].session_id requiredstring | nullThe session you reported.
scores[].received_at requiredstringWhen the request was scored.
scores[].ip requiredstring | nullA keyed hash of the IP address, never the address itself.
scores[].model_requested requiredstring | nullThe model requested.
scores[].estimated_prompt_tokens requiredinteger | nullThe estimate you sent.
scores[].score requirednumber | nullThe score.
scores[].tier requiredstring | nullThe tier. One of low, medium, high.
scores[].reasons requiredstring[] | nullThe reasons.
scores[].shadow_mode requiredbooleanWhether cold-start rules produced it.
scores[].deep_mode_active requiredbooleanAlways false.
total requiredintegerAll scores for the account.
limit requiredintegerThe page size used.
offset requiredintegerThe offset used.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

GET /v1/stats

Workspace totals

Account counts by latest tier and label, and activity in the last 24 hours.

Example request

curl -X GET https://api.infertrail.com/v1/stats \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

Totals.

FieldTypeDescription
total_accounts requiredintegerAll accounts.
high_risk_accounts requiredintegerAccounts whose latest tier is high.
medium_risk_accounts requiredintegerLatest tier medium.
low_risk_accounts requiredintegerLatest tier low.
unscored_accounts requiredintegerNever scored.
labeled_fraud requiredintegerLabelled fraud.
labeled_legitimate requiredintegerLabelled legitimate.
unlabeled requiredintegerWithout a label.
scores_24h requiredintegerScores in the last 24 hours.
events_24h requiredintegerCompleted calls recorded in the last 24 hours.

Errors

401The API key is missing, unknown, revoked, or not a secret key.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

GET /v1/integration/status

Check your integration

Which fields your calls actually send, how often, and which detections are unavailable because a signal is missing.

Parameters

NameInDescription
windowquery, stringPeriod to inspect. One of 1h, 24h, 7d, 30d. Default 7d.

Example request

curl -X GET https://api.infertrail.com/v1/integration/status \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

Coverage of your signals.

FieldTypeDescription
window requiredstringThe period inspected.
estimated requiredbooleanWhether the counts are estimates.
detections_unavailable requiredstring[]Detections that need a signal you don't send.
payloads requiredobject[]Per endpoint.
payloads[].endpointstringThe endpoint.
payloads[].callsintegerCalls in the period.
payloads[].signalsobject[]Per-field coverage.
payloads[].signals[].pathstringField path in the request.
payloads[].signals[].tierstringHow much it matters. One of required, high_yield, optional.
payloads[].signals[].presentnumber | nullShare of calls that sent it, from 0 to 1.
payloads[].signals[].detectsstring[]What it helps detect.
payloads[].signals[].sends_prompt_contentbooleanAlways false.
payloads[].signals[].descriptionstringWhat the field is.
payloads[].signals[].notestringAdvice on sending it.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

Signups

Score new signups and record what they turned out to be.

POST /v1/registrations/score

Score a signup

Score a new signup before you create the account. Keep the returned registration_id and pass it to POST /v1/identity once the account exists, to link the two.

Request body

FieldTypeDescription
email requiredstringThe email address the user signed up with.
event_idstringYour idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event.
ipstringThe user's IP address.
ip_hashstringYour hash of the IP address, used when ip is absent.
asnintegerAutonomous system number.
ip_countrystringCountry of the IP address.
declared_countrystringThe country the user entered.
user_agentstringThe User-Agent header.
device_fingerprintstringYour device fingerprint.
sensor_tokenstringA browser sensor token.
clientobjectBrowser signals.
client.webdriverbooleannavigator.webdriver.
client.fingerprint_anomalynumberYour fingerprint anomaly score.
client.load_to_submit_msnumberTime from page load to submit.
client.timezonestringThe browser's time zone.
formobjectForm interaction timing.
form.load_to_submit_msnumberTime from form display to submit.
form.fieldsobjectPer-field interaction metadata. Never field values.
phonestringThe phone number entered.
usernamestringThe username chosen.
referrerstringThe referring page.
deadline_msintegerHow long you can wait for an answer, in milliseconds.

Example request

curl -X POST https://api.infertrail.com/v1/registrations/score \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "new.user@example.com",
  "event_id": "signup_9001",
  "ip": "198.51.100.23",
  "user_agent": "Mozilla/5.0",
  "declared_country": "US"
}'

Response 200

The signup's score.

FieldTypeDescription
registration_id requiredstringKeep this to link the signup to its account.
tier requiredintegerRisk level as a number.
score requirednumberRisk from 0 to 1.
reasons requiredstring[]Machine-readable reasons.
duplicatebooleanTrue when this event_id was already scored.
shadow_modebooleanWhether the score is observe-only.
degradedstring[]Signals that could not be checked in time.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

POST /v1/registrations/{registration_id}/label

Label a signup

Record what a signup turned out to be. Send an Idempotency-Key header so a retry is not applied twice.

Parameters

NameInDescription
registration_id requiredpath, stringThe registration_id from the signup's score.
Idempotency-Keyheader, stringYour key for this label request; send exactly one.

Request body

FieldTypeDescription
label requiredstringYour verdict. One of fraud, legitimate.

Example request

curl -X POST https://api.infertrail.com/v1/registrations/{registration_id}/label \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "legitimate"
}'

Response 200

Recorded.

FieldTypeDescription
accepted requiredbooleanAlways true on success.
{
  "accepted": true
}

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
403The key may not use this route.
404Nothing with that identifier belongs to your workspace.
409Another request with the same idempotency key is still in progress.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.
504The request did not finish in time. Retry with the same idempotency key.

Browser sensor

Collect browser signals with a publishable key and verify them from your backend.

POST /v1/sensor/collect

Collect browser signals

Called from the browser with your publishable key (pk_live_…) in siteKey, not a secret key. Returns a short-lived signed token; pass it to your backend and on to POST /v1/score as request.sensor_token or to POST /v1/sensor/verify. The request must come from an origin you allowed for that key.

Request body

FieldTypeDescription
siteKey requiredstringYour publishable key.
vintegerPayload version.
sessionIdstringYour session identifier.
actionstring | nullWhat the user is doing, such as login.
fingerprintstringA device fingerprint.
loadedEpochintegerWhen the page loaded, in Unix milliseconds.
collectedAtMsintegerWhen signals were collected.
urlstringThe page URL.
referrerstring | nullThe referring page.
environmentobjectBrowser environment: user agent, languages, platform, hardware, time zone, canvas and WebGL identifiers.
automationobjectAutomation indicators, such as webdriver and known headless traits.
behaviorobjectInteraction counts: mouse movement, clicks, keys, scrolls and touches.

Example request

curl -X POST https://api.infertrail.com/v1/sensor/collect

Response 200

A signed token and an early decision.

FieldTypeDescription
token requiredstringValid for two minutes.
decision requiredstringEarly read on the browser. One of allow, challenge, deny.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.

POST /v1/sensor/verify

Verify a sensor token

From your backend, with your secret key: check a token from POST /v1/sensor/collect and get the browser's verdict.

Request body

FieldTypeDescription
token requiredstringThe token from collect.
actionstringThe action you expect, if you set one at collect.

Example request

curl -X POST https://api.infertrail.com/v1/sensor/verify \
  -H "Authorization: Bearer $INFERTRAIL_SECRET_KEY"

Response 200

The browser's verdict.

FieldTypeDescription
is_bot requiredbooleanWhether the browser looks automated.
is_human requiredbooleanWhether it looks human.
score requirednumberBot likelihood from 0 to 1.
decision requiredstringWhat to do. One of allow, challenge, deny.
reasons requiredstring[]Why.

Errors

400The request is malformed, too large, or contains prompt or response content.
401The API key is missing, unknown, revoked, or not a secret key.
403The key may not use this route.
429The key exceeded its request rate. Retry after a short wait.
503InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice.