Events

Every /trace call is anchored to an event: a specific user action your system wants to evaluate. Policies are scoped to event types, so the rules you write for a login are separate from the rules you write for a signup, each with the signals and thresholds that make sense for that action.

Event types

Event	What it represents
`signup`	A new account creation attempt
`login`	An authentication attempt against an existing account
`otp`	A one-time passcode send request (SMS, voice, or email)
`transaction`	A payment or other high-value action within an authenticated session

Each event type gets its own policy under Guard. A policy for signup can deny disposable emails and automation; a policy for login can deny credential stuffing based on per-IP failure velocity (rules that would be irrelevant on the other type).

Status

Every event has a status: attempted, succeeded, or failed.

Status	Meaning
`attempted`	The request is being evaluated. Outcome is not yet known; this is the status at the edge before the request reaches your origin.
`succeeded`	The action completed successfully (account created, user authenticated, OTP sent, payment accepted).
`failed`	The action was rejected by your system (wrong password, OTP rate-limit hit, payment declined).

How status is determined

Status reaches tracenow in two ways depending on where the trace originates. At the Cloudflare edge (outcome trace) The Worker fires an initial trace with status: attempted before the request reaches your origin. Once your origin responds, the Worker maps the HTTP response code to an outcome and fires a second, non-blocking trace:

2xx → succeeded
4xx / 5xx → failed

You configure this mapping per route when you set up the integration. The second trace is async, so it adds zero latency to the user-facing response. In the in-app call When you call /trace from your backend, you set status directly to the real outcome you observed. This is always more accurate than the HTTP-code mapping because your server knows exactly what happened: a 200 login response could still mean a wrong-password rejection depending on your API design.

The in-app call lets you pass status: "failed" even if your server returns 200. Use it whenever your response shape doesn’t map cleanly to HTTP codes.

Why status matters

Status is a first-class signal. You can write rules against event.status directly, which unlocks the most powerful account-takeover patterns:

Credential stuffing: velocity.ip.failed_count_1h gt 5 AND event.status eq "failed". Blocks an IP racking up login failures.
Suspicious success after failures: velocity.user.failed_count_1h gt 3 AND event.status eq "succeeded". Challenges a login that succeeds after a brute-force run.
New country on success: ip.is_new_country_for_user AND event.status eq "succeeded". Challenges a login from a country the account has never used.

Without status, none of these conditions are expressible. Without the in-app call, the outcome comes from HTTP code mapping. That is close enough for most apps, but the in-app call gives you exact control when you need it.

Event × status reference

Event	Typical statuses	Notes
`signup`	`attempted`, `succeeded`, `failed`	Edge fires `attempted`; outcome trace fires `succeeded`/`failed` once the account is created or rejected.
`login`	`attempted`, `succeeded`, `failed`	`failed` is the key signal for credential stuffing and brute-force rules.
`otp`	`attempted`, `succeeded`, `failed`	`attempted` is the dominant signal for SMS pumping. The damage happens before the code is verified.
`transaction`	`attempted`, `succeeded`, `failed`	`failed` can indicate card testing.

What goes into an event

Beyond the type and status, a trace carries the signals tracenow enriches and evaluates:

{
  "event": "login",
  "status": "failed",
  "ip": "203.0.113.42",
  "email": "user@example.com",
  "phone": "+14155552671",
  "device_token": "dt_...",
  "subject_user_id": "usr_123",
  "visitor_id": "dv_...",
  "properties": {}
}

Send whatever you have. Not all fields are required. subject_user_id is only available from the in-app call; the edge never has it. See Server-side integration for the full field reference.

Next steps

Signals

Every field your rules can evaluate: IP, email, phone, device, velocity, and event status.

Rules

How to combine signals into conditions, and conditions into policies.

Getting started

Core concepts

Integration

Use cases

API reference

Event types

Status

How status is determined

Why status matters

Event × status reference

What goes into an event

Next steps

Signals

Rules

​Event types

​Status

​How status is determined

​Why status matters

​Event × status reference

​What goes into an event

​Next steps

Signals

Rules

Event types

Status

How status is determined

Why status matters

Event × status reference

What goes into an event

Next steps