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.
- 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. - Score before you serve. From your backend, call
POST /v1/scorewith your identifier for the user's account and what you know about the request. If the answer saysblocked: true, refuse the request. - Record what happened. When the model call finishes, send its tokens and cost to
POST /v1/events/post-call, using the sameevent_id. - 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."}
| 400 | The body is malformed, too large, or contains prompt or response content. Fix the request; retrying it unchanged won't help. |
| 401 | The key is missing, unknown, revoked, or not a secret key. |
| 403 | The key may not use this route. |
| 404 | Nothing with that identifier belongs to your workspace. |
| 409 | Another request with the same idempotency key is still in progress. |
| 413 | A batch exceeds its size limit. |
| 429 | The key is sending too fast. Wait briefly and retry. |
| 503, 504 | InferTrail 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_idand others): at most 256 characters. event_timein 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
| Field | Type | Description |
|---|---|---|
account_id required | string | Your identifier for the end user's account. Required and not blank. |
event_id | string | null | Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event. |
session_id | string | null | Your identifier for the user's session, if you have one. |
account | object | null | What you know about the account. Only these three keys are accepted. |
account.subscription_tier | string | null | Your name for the account's subscription tier. |
account.first_seen | string | null | When the account was created, as an RFC 3339 timestamp with a time zone. |
account.context | object | null | Facts you attest about the account. A null, empty or unrecognized value changes nothing; recognized values overlay what InferTrail already stores. |
account.context.plan_type | string | null | The account's plan. Recognized values: paid, unpaid, trial, free (any case). Other values are ignored. |
account.context.has_payment_method | boolean | null | Whether a payment method is on file. |
account.context.email_verified | boolean | null | Whether the account's email address is verified. |
account.context.identity_verified | boolean | null | Whether you have verified the account holder's identity. |
account.context.prior_chargeback | boolean | null | Whether the account has had a chargeback. |
account.context.billing_delinquent | boolean | null | Whether the account is behind on payments. |
account.context.trust_label | string | null | Your trust assertion. Recognized values: vip, allowlisted, allowlist, trusted (any case). |
request | object | null | Metadata about this request. Never include prompt or response text. |
request.ip | string | null | The end user's IP address. |
request.ip_hash | string | null | Your own hash of the end user's IP address, used only when ip is absent. At most 128 characters. |
request.asn | integer | null | The autonomous system number of the end user's network. |
request.ip_country | string | null | Two-letter country code of the end user's IP address. Malformed values are dropped. |
request.user_agent | string | null | The end user's User-Agent header. |
request.model_requested | string | null | The model the user asked for. |
request.estimated_prompt_tokens | integer | null | Your estimate of the prompt's size in tokens. |
request.sensor_token | string | null | A token from POST /v1/sensor/collect. Accepted, but not yet used in the score; see signals_fused. |
request.session_signals | object | null | Behavioral timing you observed in the session. |
request.session_signals.ms_since_last_request | integer | null | Milliseconds since this session's previous request. |
request.session_signals.ms_since_page_load | integer | null | Milliseconds since the page that sent the request loaded. |
request.session_signals.interaction_events_count | integer | null | Number of user interactions (clicks, keys, scrolls) seen in the session. |
request.session_signals.ms_since_signup | integer | null | Milliseconds since the account signed up. |
request.session_signals.is_first_request_in_session | boolean | null | Whether this is the session's first request. |
request.client | object | null | Client-side automation signals. |
request.client.webdriver | boolean | null | Whether 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.
| Field | Type | Description |
|---|---|---|
event_id | string | The event's ID: yours, or one InferTrail generated when you sent none. |
score required | number | Risk from 0 (benign) to 1 (abusive). |
tier required | string | Risk 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 required | string[] | Machine-readable reasons, most important first. scoring_unavailable means scoring failed and the answer is a safe default. |
blocked required | boolean | Whether you should refuse the request: a manual block or an exceeded spend cap applies. |
shadow_mode required | boolean | True while the account has too little history for the trained model; the score then comes from cold-start rules. |
baseline_ready required | boolean | True once the account's history is sufficient for the trained model. |
deep_mode_active required | boolean | Always false. InferTrail never inspects prompt content. |
signals_fused required | boolean | Currently always false: browser sensor signals are not yet combined into scores. Check a sensor token with POST /v1/sensor/verify. |
duplicate | boolean | Present and true when this event_id was already scored; the original answer is returned unchanged. |
algorithm | string | Name of the scoring method that produced the score. |
algorithm_version | string | Version of that method. |
service_version | string | Version of the scoring service. |
scorer_version | string | Version of the full scorer, including its rules. |
grouping | object | Evidence 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
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 405 | Wrong HTTP method; the Allow header names the right one. |
| 503 | InferTrail 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
| Field | Type | Description |
|---|---|---|
account_id required | string | The account that made the call. Required and not blank. |
event_id | string | Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event. |
session_id | string | null | Your identifier for the user's session. |
model | string | null | The model that served the call. |
prompt_tokens | integer | null | Prompt tokens used. Null or absent means unknown, not zero. |
completion_tokens | integer | null | Completion tokens used. Null or absent means unknown, not zero. |
latency_ms | integer | null | How long the call took, in milliseconds. |
inference_cost_usd | number | null | What the call cost you, in US dollars. When omitted, InferTrail estimates it from tokens and marks the estimate. |
telemetry | object | Timing of the completed model call. |
telemetry.version required | integer | 1, or 2 to include model_id and stream. One of 1, 2. |
telemetry.source_id required | string | Your identifier for the system that served the call, at most 128 bytes. |
telemetry.model_family required | string | Size class of the model. One of small, medium, large, reasoning. |
telemetry.model_id | string | Version 2 only: the exact model identifier, at most 256 bytes. |
telemetry.stream | boolean | null | Version 2 only: whether the response was streamed. |
telemetry.status required | integer | HTTP status your model call returned. |
telemetry.start_ts required | number | When the call started, in Unix seconds. |
telemetry.end_ts required | number | When 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.
| Field | Type | Description |
|---|---|---|
ok required | boolean | Always true on success. |
accepted required | boolean | The event is durably queued. Pricing and spend caps are applied after the answer. |
event_id required | string | The event's ID: yours, or one InferTrail generated. |
{
"ok": true,
"accepted": true,
"event_id": "req_8f3a"
}Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 405 | Wrong HTTP method; the Allow header names the right one. |
| 503 | InferTrail 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
| Field | Type | Description |
|---|---|---|
account_id required | string | The account the identity event belongs to. |
event_id | string | Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event. |
session_id | string | null | Your identifier for the user's session. |
event_type | string | null | What happened, such as login, signup or password_reset. |
ip | string | null | The user's IP address. |
ip_hash | string | null | Your own hash of the IP address, used only when ip is absent. |
asn | integer | null | Autonomous system number of the user's network. |
ip_country | string | null | Two-letter country code of the IP address. |
user_agent | string | null | The user's User-Agent header. |
registration_id | string | null | The 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.
| Field | Type | Description |
|---|---|---|
ok required | boolean | Always true on success. |
duplicate | boolean | Present and true when this event_id was already recorded. |
{
"ok": true
}Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 405 | Wrong HTTP method; the Allow header names the right one. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail 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
| Field | Type | Description |
|---|---|---|
account_id required | string | The account to label. |
label required | string | Your verdict. One of fraud, legitimate. |
notes | string | Free-text notes for your team. Do not include personal data you don't need. |
event_id | string | Your 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.
| Field | Type | Description |
|---|---|---|
ok required | boolean | Always true on success. |
duplicate | boolean | Present and true when this event_id was already recorded. |
{
"ok": true
}Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 405 | Wrong HTTP method; the Allow header names the right one. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail 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
| Name | In | Description |
|---|---|---|
account_id required | path, string | Your identifier for the end user's account, URL-encoded. |
Request body
| Field | Type | Description |
|---|---|---|
plan_type | string | null | The account's plan. Recognized values: paid, unpaid, trial, free (any case). Other values are ignored. |
has_payment_method | boolean | null | Whether a payment method is on file. |
email_verified | boolean | null | Whether the account's email address is verified. |
identity_verified | boolean | null | Whether you have verified the account holder's identity. |
prior_chargeback | boolean | null | Whether the account has had a chargeback. |
billing_delinquent | boolean | null | Whether the account is behind on payments. |
trust_label | string | null | Your 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.
| Field | Type | Description |
|---|---|---|
ok required | boolean | Always true on success. |
duplicate | boolean | Present and true when this event_id was already recorded. |
{
"ok": true
}Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 405 | Wrong HTTP method; the Allow header names the right one. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail 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
| Field | Type | Description |
|---|---|---|
events required | object[] | 1 to 100 events. 1 to 100 items. |
events[].event_id required | string | Required idempotency key, at most 256 characters, unique within the request. |
events[].type required | string | The event's kind. One of post_call, identity. |
events[].event_time | string | When the event happened, at most seven days ago and one minute ahead. Defaults to the time InferTrail received it. |
events[].data required | object | The 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.
| Field | Type | Description |
|---|---|---|
acceptance | string | Always queue. |
accepted | integer | Number of events queued. |
processing | string | Always asynchronous. |
events | object[] | One receipt per event, in request order. |
events[].event_id | string | The event's ID. |
events[].receipt_id | string | The receipt to check. |
events[].status | string | Always queued. |
events[].status_url | string | Path 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
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 405 | Wrong HTTP method; the Allow header names the right one. |
| 413 | The batch exceeds its size limit. |
| 503 | InferTrail 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
| Name | In | Description |
|---|---|---|
receipt_id required | path, string | The 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.
| Field | Type | Description |
|---|---|---|
receipt_id | string | The receipt's ID. |
event_id | string | The event's ID. |
type | string | The event's kind. |
event_time | string | When the event happened. |
received_at | string | When InferTrail received it. |
status required | string | queued 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_at | string | When processing finished. |
error | string | Why 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
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 403 | The key may not use this route. |
| 404 | Nothing with that identifier belongs to your workspace. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice. |
| 504 | The 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
| Name | In | Description |
|---|---|---|
event_id required | path, string | Your 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.
| Field | Type | Description |
|---|---|---|
receipt_id | string | The receipt's ID. |
event_id | string | The event's ID. |
type | string | The event's kind. |
event_time | string | When the event happened. |
received_at | string | When InferTrail received it. |
status required | string | queued 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_at | string | When processing finished. |
error | string | Why processing did not complete. |
Errors
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 403 | The key may not use this route. |
| 404 | Nothing with that identifier belongs to your workspace. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice. |
| 504 | The 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.
| Field | Type | Description |
|---|---|---|
window_seconds required | integer | How far back the counts reach. |
counts required | object | |
counts.completed | integer | Processed. |
counts.conflict | integer | Rejected for reusing an event ID with different data. |
counts.failed | integer | Failed after retries. |
recent required | object[] | The latest events. |
recent[].receipt_id | string | The receipt's ID. |
recent[].event_id | string | The event's ID. |
recent[].type | string | The event's kind. |
recent[].event_time | string | When the event happened. |
recent[].received_at | string | When InferTrail received it. |
recent[].status required | string | queued 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_at | string | When processing finished. |
recent[].error | string | Why processing did not complete. |
Errors
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 403 | The key may not use this route. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice. |
| 504 | The 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
| Name | In | Description |
|---|---|---|
sort | query, string | What to sort by. One of score, last_seen, first_seen, requests, spend. Default score. |
order | query, string | Sort direction. One of asc, desc. Default desc. |
label | query, string | Only accounts with this label. One of fraud, legitimate, unlabeled. |
tier | query, string | Only accounts whose latest tier is this. One of low, medium, high. |
min_score | query, number | Only accounts whose latest score is at least this. |
window | query, string | How far back usage totals reach, counted from the start of the current hour. One of 1h, 1d, 7d, 30d. Default 30d. |
limit | query, integer | Page size. Values above 200 are capped at 200. Default 50. |
offset | query, integer | Number 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.
| Field | Type | Description |
|---|---|---|
accounts required | object[] | The page. |
accounts[].account_id required | string | Your account identifier. |
accounts[].first_seen required | string | When InferTrail first saw the account. |
accounts[].last_seen required | string | When InferTrail last saw activity. |
accounts[].subscription_tier required | string | null | The subscription tier you reported. |
accounts[].request_count required | integer | Scored requests for the account. |
accounts[].last_label required | string | null | Your most recent label. One of fraud, legitimate. |
accounts[].last_label_at required | string | null | When you labelled the account. |
accounts[].latest_score required | number | null | The most recent score. |
accounts[].latest_tier required | string | null | The most recent tier. One of low, medium, high. |
accounts[].scored_at required | string | null | When the most recent score was given. |
accounts[].inference_cost_usd required | number | Spend in the window, in US dollars. |
total required | integer | Accounts matching the filters. |
limit required | integer | The page size used. |
offset required | integer | The offset used. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 503 | InferTrail 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
| Name | In | Description |
|---|---|---|
account_id required | path, string | Your identifier for the end user's account, URL-encoded. |
window | query, string | How 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.
| Field | Type | Description |
|---|---|---|
account_id required | string | Your account identifier. |
first_seen required | string | When InferTrail first saw the account. |
last_seen required | string | When it was last active. |
subscription_tier required | string | The subscription tier you reported. |
request_count required | integer | Scored requests. |
latest_score required | object | |
latest_score.score required | number | The score. |
latest_score.tier required | string | Risk 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 required | string[] | null | Its reasons. |
latest_score.received_at required | string | When it was given. |
latest_score.shadow_mode required | boolean | Whether it came from cold-start rules. |
latest_score.deep_mode_active required | boolean | Always false. |
window required | object | Usage in the window. |
window.events required | integer | Completed calls. |
window.prompt_tokens required | integer | Prompt tokens. |
window.completion_tokens required | integer | Completion tokens. |
window.inference_cost_usd required | number | Spend in US dollars. |
model_mix required | object[] | Calls per model in the window. |
model_mix[].model required | string | Model name. |
model_mix[].count required | integer | Calls. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 404 | Nothing with that identifier belongs to your workspace. |
| 503 | InferTrail 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
| Name | In | Description |
|---|---|---|
account_id required | path, string | Your identifier for the end user's account, URL-encoded. |
limit | query, integer | Page size. Values above 200 are capped at 200. Default 50. |
offset | query, integer | Number 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.
| Field | Type | Description |
|---|---|---|
scores required | object[] | The page. |
scores[].id required | integer | A stable numeric ID for this entry. |
scores[].session_id required | string | null | The session you reported. |
scores[].received_at required | string | When the request was scored. |
scores[].ip required | string | null | A keyed hash of the IP address, never the address itself. |
scores[].model_requested required | string | null | The model requested. |
scores[].estimated_prompt_tokens required | integer | null | The estimate you sent. |
scores[].score required | number | null | The score. |
scores[].tier required | string | null | The tier. One of low, medium, high. |
scores[].reasons required | string[] | null | The reasons. |
scores[].shadow_mode required | boolean | Whether cold-start rules produced it. |
scores[].deep_mode_active required | boolean | Always false. |
total required | integer | All scores for the account. |
limit required | integer | The page size used. |
offset required | integer | The offset used. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 503 | InferTrail 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.
| Field | Type | Description |
|---|---|---|
total_accounts required | integer | All accounts. |
high_risk_accounts required | integer | Accounts whose latest tier is high. |
medium_risk_accounts required | integer | Latest tier medium. |
low_risk_accounts required | integer | Latest tier low. |
unscored_accounts required | integer | Never scored. |
labeled_fraud required | integer | Labelled fraud. |
labeled_legitimate required | integer | Labelled legitimate. |
unlabeled required | integer | Without a label. |
scores_24h required | integer | Scores in the last 24 hours. |
events_24h required | integer | Completed calls recorded in the last 24 hours. |
Errors
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 503 | InferTrail 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
| Name | In | Description |
|---|---|---|
window | query, string | Period 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.
| Field | Type | Description |
|---|---|---|
window required | string | The period inspected. |
estimated required | boolean | Whether the counts are estimates. |
detections_unavailable required | string[] | Detections that need a signal you don't send. |
payloads required | object[] | Per endpoint. |
payloads[].endpoint | string | The endpoint. |
payloads[].calls | integer | Calls in the period. |
payloads[].signals | object[] | Per-field coverage. |
payloads[].signals[].path | string | Field path in the request. |
payloads[].signals[].tier | string | How much it matters. One of required, high_yield, optional. |
payloads[].signals[].present | number | null | Share of calls that sent it, from 0 to 1. |
payloads[].signals[].detects | string[] | What it helps detect. |
payloads[].signals[].sends_prompt_content | boolean | Always false. |
payloads[].signals[].description | string | What the field is. |
payloads[].signals[].note | string | Advice on sending it. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 503 | InferTrail 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
| Field | Type | Description |
|---|---|---|
email required | string | The email address the user signed up with. |
event_id | string | Your idempotency key for this event, at most 256 characters. Reusing it returns the first result instead of recording a second event. |
ip | string | The user's IP address. |
ip_hash | string | Your hash of the IP address, used when ip is absent. |
asn | integer | Autonomous system number. |
ip_country | string | Country of the IP address. |
declared_country | string | The country the user entered. |
user_agent | string | The User-Agent header. |
device_fingerprint | string | Your device fingerprint. |
sensor_token | string | A browser sensor token. |
client | object | Browser signals. |
client.webdriver | boolean | navigator.webdriver. |
client.fingerprint_anomaly | number | Your fingerprint anomaly score. |
client.load_to_submit_ms | number | Time from page load to submit. |
client.timezone | string | The browser's time zone. |
form | object | Form interaction timing. |
form.load_to_submit_ms | number | Time from form display to submit. |
form.fields | object | Per-field interaction metadata. Never field values. |
phone | string | The phone number entered. |
username | string | The username chosen. |
referrer | string | The referring page. |
deadline_ms | integer | How 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.
| Field | Type | Description |
|---|---|---|
registration_id required | string | Keep this to link the signup to its account. |
tier required | integer | Risk level as a number. |
score required | number | Risk from 0 to 1. |
reasons required | string[] | Machine-readable reasons. |
duplicate | boolean | True when this event_id was already scored. |
shadow_mode | boolean | Whether the score is observe-only. |
degraded | string[] | Signals that could not be checked in time. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail 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
| Name | In | Description |
|---|---|---|
registration_id required | path, string | The registration_id from the signup's score. |
Idempotency-Key | header, string | Your key for this label request; send exactly one. |
Request body
| Field | Type | Description |
|---|---|---|
label required | string | Your 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.
| Field | Type | Description |
|---|---|---|
accepted required | boolean | Always true on success. |
{
"accepted": true
}Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 403 | The key may not use this route. |
| 404 | Nothing with that identifier belongs to your workspace. |
| 409 | Another request with the same idempotency key is still in progress. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice. |
| 504 | The 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
| Field | Type | Description |
|---|---|---|
siteKey required | string | Your publishable key. |
v | integer | Payload version. |
sessionId | string | Your session identifier. |
action | string | null | What the user is doing, such as login. |
fingerprint | string | A device fingerprint. |
loadedEpoch | integer | When the page loaded, in Unix milliseconds. |
collectedAtMs | integer | When signals were collected. |
url | string | The page URL. |
referrer | string | null | The referring page. |
environment | object | Browser environment: user agent, languages, platform, hardware, time zone, canvas and WebGL identifiers. |
automation | object | Automation indicators, such as webdriver and known headless traits. |
behavior | object | Interaction counts: mouse movement, clicks, keys, scrolls and touches. |
Example request
curl -X POST https://api.infertrail.com/v1/sensor/collectResponse 200
A signed token and an early decision.
| Field | Type | Description |
|---|---|---|
token required | string | Valid for two minutes. |
decision required | string | Early read on the browser. One of allow, challenge, deny. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail 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
| Field | Type | Description |
|---|---|---|
token required | string | The token from collect. |
action | string | The 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.
| Field | Type | Description |
|---|---|---|
is_bot required | boolean | Whether the browser looks automated. |
is_human required | boolean | Whether it looks human. |
score required | number | Bot likelihood from 0 to 1. |
decision required | string | What to do. One of allow, challenge, deny. |
reasons required | string[] | Why. |
Errors
| 400 | The request is malformed, too large, or contains prompt or response content. |
| 401 | The API key is missing, unknown, revoked, or not a secret key. |
| 403 | The key may not use this route. |
| 429 | The key exceeded its request rate. Retry after a short wait. |
| 503 | InferTrail could not complete the request. Retry with the same event_id; it will not be recorded twice. |