Skip to main content
GET
List your application's visits

Authorizations

X-API-Key
string
header
required

Query Parameters

limit
integer
default:10

Maximum number of records to return in a single page. Must be between 1 and 1000.

Required range: 1 <= x <= 1000
offset
integer | null

Number of records to skip from the beginning. Use 0 for the first page. Cannot be used with cursor.

Required range: x >= 0
cursor
string | null

Opaque pagination cursor token that identifies the position in the result set. Use the cursor from the previous response to get the next page. Cannot be used with offset.

sort
enum<string> | null

started_at: the visit's first record; last_seen_at: its latest. Ties break on the visit's id. Defaults to started_at desc. The field a visit list sorts on.

Available options:
started_at,
last_seen_at
sort_direction
enum<string> | null

asc or desc, for every key of the sort. Defaults to the field's own: started_at desc, last_seen_at desc.

Available options:
asc,
desc
presence_kind
enum<string>[] | null

Only this presence kind now. Repeat for several.

What is behind a request at a merchant: a person, an AI agent, a crawler, other automation, or not yet known.

Available options:
human,
agent,
crawler,
automation,
unknown
presence_trust
enum<string>[] | null

Only this presence trust now. Repeat for several.

How strongly the evidence backs a request's presence, strongest first: credentialed (a KYA credential), verified (a verified signature such as Web Bot Auth), declared (a User-Agent corroborated by the platform's published IP range), scored (a detection verdict), unobserved (the first request of a browser visit, before any evidence), none (evidence that did not corroborate).

Available options:
credentialed,
verified,
declared,
scored,
unobserved,
none
identity_level
enum<string>[] | null

Only visits that reached this identity level. Repeat for several.

The deepest identity established for a visitor, lowest to highest: L1 the operator is known, L2 a consistent per-person identifier (pseudonymous), L3 a verified-identity credential.

Available options:
L1,
L2,
L3
transport
enum<string>[] | null

Only this transport. Repeat for several.

How a visitor reached the merchant. Values may be added.

Available options:
browser,
api,
mcp,
ucp
state
enum<string>[] | null

Only visits in this state. Repeat for several.

Whether a visit is still going: a visit ends after 30 minutes idle.

Available options:
active,
ended
outcome
enum<string>[] | null

Only visits that ended this way. Repeat for several.

How a visit ended for the merchant. Values may be added.

Available options:
converted,
abandoned,
blocked
agent_key_thumbprint
string[] | null

Only this agent key. Repeat for several.

credential_id
string[] | null

Only visits whose latest verified credential has this jti. Repeat for several.

credential_subject
string[] | null

Only visits whose latest verified credential has this subject. Repeat for several.

start_date
string<date> | null

Filter records created on or after this date (format: YYYY-MM-DD).

end_date
string<date> | null

Filter records created on or before this date (format: YYYY-MM-DD).

tz
string
default:UTC

IANA timezone identifier used to interpret start_date and end_date (defaults to UTC).

Examples:

"UTC"

"America/Los_Angeles"

"Europe/London"

Response

Visits in the requested order.

visit_id
string<uuid>
required

The visit's id.

environment
enum<string>
required

The application's environment.

Available options:
sandbox,
production
state
enum<string>
required

Whether it goes on.

Available options:
active,
ended
presence
VisitPresence (v1) · object
required

The visitor's presence now.

decision_count
integer
required

Its decisions so far.

Required range: x >= 0
started_at
string<date-time>
required

Its first record.

last_seen_at
string<date-time>
required

Its latest record.

funnel_stage
enum<string>
required

The furthest stage it reached.

Available options:
arrived,
admitted,
browsed,
carted,
checked_out,
converted
identity_stage
enum<string>
required

How far its identity got, from its presence trust: credentialed once any decision verified a credential, verified_agent for a verified signature, declared for a corroborated claim, and anonymous otherwise.

Available options:
anonymous,
declared,
verified_agent,
credentialed
transport
enum<string> | null

How the visitor arrived: browser when it has only browser events; null when no record says.

Available options:
browser,
api,
mcp,
ucp
outcome
enum<string> | null

How it ended; null while active.

Available options:
converted,
abandoned,
blocked
first_step
enum<string> | null

The step of its first decision; null when it has none.

Available options:
browse,
search,
cart,
checkout,
payment,
account,
signup,
write
last_step
enum<string> | null

The step of its latest decision; null when it has none.

Available options:
browse,
search,
cart,
checkout,
payment,
account,
signup,
write
identity_level
enum<string> | null

The deepest identity any of its decisions had.

Available options:
L1,
L2,
L3
agent
VisitAgent (v1) · object | null

The agent behind it.

credential
VisitVerifiedCredential (v1) · object | null

The latest KYA credential the SDK verified on it; null when none.

ended_at
string<date-time> | null

When it ended; null while active.

recognized_by
enum<string> | null

What the visitor was recognized by; null when nothing recognized it.

Available options:
detection,
user_agent,
web_bot_auth,
credential
risk_score
integer | null

The risk its latest detection update scored, 0 to 100; null before one, or when the update carried no score.

Required range: 0 <= x <= 100
journey
VisitJourney (v1) · object | null

Its page views; null when it viewed no page.

detection_label
VisitDetectionLabel (v1) · object | null

The tool, product, provider or environment its latest detection update attributed it to with the highest confidence; null when none.