Skip to main content
POST
Query qualified visitor data via API key

Authorizations

X-API-Key
string
header
required

Organization API key (sk_...). Get yours from Settings > API Keys in the dashboard.

Headers

X-Whitelabel-Slug
string

Optional tenant context for admin-key operations without an organization target, such as creating an organization. Defaults to the master tenant. Must match an explicit target organization when both are supplied. Does not limit the key’s platform authority.

Required string length: 1 - 100
X-Organization-Id
string<uuid>

Target organization for admin-key requests on organization-context routes, including Data API, intent audiences and dashboard routes without an organization path parameter. Required on those routes. When supplied with an organization path parameter, both must identify the same organization; conflicting targets return 400. Does not grant access to customer credentials.

Body

application/json
visitStatus
enum<string>

Status of the latest qualifying session in the selected period. new means it starts at this person's first recorded visit to the organization; seen_before means an earlier recorded visit exists, including outside the selected period or pixel. Known email aliases share history. This is recorded history, not proof of no untracked visits. Null means unavailable or inconsistent history, or the viewer lacks organization-wide pixel access. Existing firstSeen and returning-visitor metrics are unchanged. Omit for all; combined with the rule or saved segment before pagination and totals.

Available options:
new,
seen_before
Example:

"seen_before"

backAfter30Days
boolean

True when the latest qualifying session starts at least 30 full 24-hour days after the most recent recorded activity in an earlier non-bot session for this person in this organization. Earlier visits on other pixels or outside the selected period and rule filters still count. False means a known first visit or a shorter gap. Null means insufficient or inconsistent recorded history, or restricted pixel access. This is an additional badge, not a replacement for visitStatus; unknown history is never treated as inactivity. Omit for all. False excludes unknowns. Combined with visitStatus and qualification using AND, before pagination and totals.

Example:

true

segmentId
string<uuid> | null

Saved segment to query. Mutually exclusive with ruleAst.

ruleAst
any

Canonical RuleAST. Mutually exclusive with segmentId.

page
integer
default:1

One-based result page.

Required range: x >= 1
Example:

1

limit
integer
default:50

Rows per page. Defaults to 50; maximum 100.

Required range: 1 <= x <= 100
Example:

50

pixelId
string<uuid> | null

Restrict the query to one accessible pixel. 403 when the pixel does not belong to the API-key organization

Example:

"00000000-0000-4000-8000-000000000001"

window
enum<string>

Overrides ruleAst.window for this request, using the shared window catalog

Available options:
24h,
7d,
14d,
30d,
90d,
all,
today,
3d,
mtd,
ytd
Example:

"30d"

Response

Qualified visitor data

data
object[]
required
meta
object
required